[WIP] Commands refresh

ckaiser · ckaiser · commit 5c95025bedd9 · 2025-07-29T14:18:32.000-03:00
diff --git a/api/app_command.md b/api/app_command.md
diff --git a/api/command/AddColor.md b/api/command/AddColor.md
@@ -7,10 +7,10 @@ app.command.AddColor {
 }
 ```
 
-Adds a new color into the palette.
+Adds a new color to the palette.
 
 * `source`: Can be `"fg"`, `"bg"`, or `"color"` (default). To add the foreground, background, or a specific color respectively.
-* `color`: A [Color](../color.md#color) instance to add too the palette.
+* `color`: A [Color](../color.md#color) instance to add to the palette.
 
 ## Example
 
diff --git a/api/command/AutocropSprite.md b/api/command/AutocropSprite.md
@@ -0,0 +1,11 @@
+# AutocropSprite
+
+```lua
+app.command.AutocropSprite {
+    byGrid=bool
+}
+```
+
+Automatically crops the sprite.
+
+* `byGrid`: Aligns the crop to the grid. Optional, defaults to `false`.
diff --git a/api/command/BrightnessContrast.md b/api/command/BrightnessContrast.md
@@ -9,9 +9,7 @@ app.command.BrightnessContrast {
 }
 ```
 
-* `ui`: Shows the dialog on the screen, `true` by default. Set to
-  `false` for automatic change brightness and/or contrast without
-  asking to the user for the change.
+* `ui`: Shows the brightness dialog, `true` by default. Set to `false` to apply the changes immediately without user input or preview.
 * `channels`: A combination of [FilterChannels](../filterchannels.md#filterchannels) with
   [bitwise OR (`|`) operator](https://www.lua.org/manual/5.3/manual.html#3.4.2).
   By default it is equal to:
diff --git a/api/command/ChangeBrush.md b/api/command/ChangeBrush.md
@@ -0,0 +1,14 @@
+# ChangeBrush
+
+```lua
+app.command.ChangeBrush {
+    change=string
+    slot=int
+}
+```
+
+Changes the brush of the active tool
+
+* `change`: Can be: "increment-size", "decrement-size", "increment-angle", "decrement-angle", "flip-x", "flip-y", "flip-d", "rotate-90cw", "custom"
+* `slot`: Custom brush slot (optional, only for "custom" change)
+
diff --git a/api/command/ChangeColor.md b/api/command/ChangeColor.md
@@ -0,0 +1,13 @@
+# ChangeColor
+
+```lua
+app.command.ChangeColor {
+    target=string
+    change=string
+}
+```
+
+Changes the current foreground or background color by moving up or down on the palette by index.
+
+* `target`: Can be `"foreground"` or `"background"`
+* `change`: Can be `"increment-index"` or `"decrement-index"`
diff --git a/api/command/ChangePixelFormat.md b/api/command/ChangePixelFormat.md
@@ -6,22 +6,23 @@ app.command.ChangePixelFormat {
   dithering=string,
   ["dithering-matrix"]=string,
   rgbmap=string,
-  toGray=string
+  toGray=string,
+  fitCriteria=string
 }
 ```
 
 Changes the [ColorMode](../colormode.md) of the active [sprite](../sprite.md)
 
-* `format`: Can be `"rgb"`, `"gray"`, or `"indexed"`.
-* `dithering`: Can be `"ordered"`, `"old"` `"error-diffusion"`,
-  or empty.
-* `dithering-matrix`: It can be `"bayer8x8"`, `"bayer4x4"`, or `"bayer2x2"` (when When `dithering` is `ordered` or `old`).
-  Actually it can be a matrix ID from any extensions ([for example](https://github.com/aseprite/aseprite/blob/fc79146c56f941f834f28809f0d2c4d7fd60076c/data/extensions/bayer-matrices/package.json#L8)).
-* `rgmap`: `"octree"`, `"rgb5a3"`, or `"default"` (generally default
+* `format`: `"rgb"`, `"gray"`, or `"indexed"`.
+* `dithering`: Optional, `"ordered"`, `"old"` `"error-diffusion"`
+* `dithering-matrix`: Optional, `"bayer8x8"`, `"bayer4x4"`, or `"bayer2x2"` (when When `dithering` is `ordered` or `old`).
+  Actually it can be a matrix ID from any extension ([for example](https://github.com/aseprite/aseprite/blob/fc79146c56f941f834f28809f0d2c4d7fd60076c/data/extensions/bayer-matrices/package.json#L8)).
+* `rgbmap`: Optional, `"octree"`, `"rgb5a3"`, or `"default"` (generally default
   will be octree, but it might change in the future). If nothing is
-  specified the default configured quantization method from prefereces
+  specified the default configured quantization method from preferences
   will be used if the GUI is enabled.
-* `toGray`: `"luma"`, `"hsv"`, or `"hsl"`.
+* `toGray`: Optional, `"luma"`, `"hsv"`, or `"hsl"`.
+* `fitCriteria`: Optional, `"rgb"`, `"linearizedRGB"`, `"ciexyz"`, `"cielab"`, or `"default"`
 
 ## Example
 
diff --git a/api/command/ColorCurve.md b/api/command/ColorCurve.md
@@ -9,8 +9,7 @@ app.command.ColorCurve {
 ```
 
 * `ui`: Shows the dialog on the screen, `true` by default. Set to
-  `false` to apply the color curve filter automatically without asking
-  to the user for the change.
+  `false` to apply the color curve filter automatically without user input.
 * `channels`: A combination of [FilterChannels](../filterchannels.md#filterchannels) with
   [bitwise OR (`|`) operator](https://www.lua.org/manual/5.3/manual.html#3.4.2).
   By default it is equal to:
diff --git a/api/command/ColorQuantization.md b/api/command/ColorQuantization.md
@@ -0,0 +1,28 @@
+# ColorQuantization
+
+```lua
+app.command.ColorQuantization {
+  ui=true,
+  withAlpha=bool,
+  maxColors=int,
+  useRange=bool,
+  algorithm=string,
+}
+```
+
+* `ui`: Shows the dialog on the screen, `true` by default.
+* `withAlpha`: Create entries with alpha component, defaults to `true`
+* `maxColors`: Color amount limit, defaults to `256`
+* `useRange`: Replace current range, defaults to `false`
+* `algorithm`: One of `"default"`, `"rgb5a3"` or `"octree"`
+
+## Example
+
+```lua
+app.command.ColorQuantization {
+  ui=true,
+  withAlpha=false,
+  maxColors=100,
+  algorithm="octree"
+}
+```
diff --git a/api/command/ConvolutionMatrix.md b/api/command/ConvolutionMatrix.md
@@ -4,7 +4,7 @@
 app.command.ConvolutionMatrix {
   ui=true,
   channels=FilterChannels...,
-  tiledMode=none,
+  tiledMode=string,
   fromResource=string
 }
 ```
diff --git a/api/command/CropSprite.md b/api/command/CropSprite.md
@@ -0,0 +1,18 @@
+# CropSprite
+
+```lua
+app.command.CropSprite {
+    x=int,
+    y=int,
+    width=int,
+    height=int
+}
+```
+
+Crops the sprite to the given bounds.
+All parameters default to 0, if none are not given, the sprite will be cropped to the mask bounds.
+
+* `x`: The X value of the crop bounds
+* `x`: The Y value of the crop bounds
+* `width`: The crop width
+* `height`: The crop height
diff --git a/api/command/DuplicateSprite.md b/api/command/DuplicateSprite.md
@@ -0,0 +1,15 @@
+# DuplicateSprite
+
+```lua
+app.command.DuplicateSprite {
+  ui=bool,
+  filename=string,
+  flatten=bool
+}
+```
+
+Duplicates the current sprite
+
+* `ui`: Shows the duplicate dialog, `true` by default. Set to `false` to create the duplicate automatically.
+* `filename`: New filename for the sprite, if left empty it will auto-generate a new one.
+* `flatten`: Duplicate merged layers only. Defaults to `false`.
diff --git a/api/command/ExportTileset.md b/api/command/ExportTileset.md
@@ -11,4 +11,4 @@ This is similar to
 using [the `-export-tileset` argument from the CLI](https://www.aseprite.org/docs/cli/#export-tileset)
 with [`-format=json-array` option](https://www.aseprite.org/docs/cli/#format).
 
-This command accept the same parameters as [app.command.SaveFileCopyAs](SaveFile.md#savefile).
+This command accepts the same parameters as [app.command.SaveFileCopyAs](SaveFile.md#savefile).
diff --git a/api/command/FlattenLayers.md b/api/command/FlattenLayers.md
@@ -0,0 +1,11 @@
+# FlattenLayers
+
+```lua
+app.command.FlattenLayers {
+    visibleOnly=bool
+}
+```
+
+Flattens the current layers into one.
+
+* `visibleOnly`: Set to `true` to only flatten the visible layers, defaults to `false`.
diff --git a/api/command/Flip.md b/api/command/Flip.md
@@ -0,0 +1,15 @@
+# Flip
+
+```lua
+app.command.Flip {
+    target=string
+    orientation=string
+}
+```
+
+Flips the whole sprite or the current selection mask, either vertically or horizontally.
+
+Note: When specifying `target=mask` without a UI or with no active mask, the entire sprite will be flipped.
+
+* `target`: Can be `"mask"` or `"sprite"`. Defaults to "`sprite`".
+* `change`: Can be `"vertical"` or `"horizontal"`. Defaults to "`horizontal`".
diff --git a/api/command/FrameProperties.md b/api/command/FrameProperties.md
@@ -0,0 +1,11 @@
+# FrameProperties
+
+```lua
+app.command.FrameProperties {
+    frame=string or integer
+}
+```
+
+Shows the Frame Properties dialog
+
+* `target`: Can be `"all"`, `"current"` or the frame number. Defaults to "`all`".
diff --git a/api/command/FrameTagProperties.md b/api/command/FrameTagProperties.md
@@ -0,0 +1,11 @@
+# FrameProperties
+
+```lua
+app.command.FrameProperties {
+    name=string
+}
+```
+
+Shows the Frame Tag Properties dialog for the given name, or the first tag if no name is given.
+
+`name`: Tag name.
diff --git a/api/command/LoadMask.md b/api/command/LoadMask.md
@@ -0,0 +1,15 @@
+# LoadMask
+
+```lua
+app.command.LoadMask {
+  ui=true,
+  filename="string"
+}
+```
+
+Loads a mask from the given *.msk file.
+
+* `ui`: Shows the file picker dialog with `filename` pre-completed, `true` by default. Set to
+  `false` to load `filename`directly without user confirmation.
+* `filename`: A path to a *.msk file or a path to pre-load into the file picker dialog.
+
diff --git a/api/command/LoadPalette.md b/api/command/LoadPalette.md
@@ -0,0 +1,17 @@
+# LoadPalette
+
+```lua
+app.command.LoadPalette {
+  ui=true,
+  filename="string"
+  preset="string"
+}
+```
+
+Loads a palette from the given `preset` or `filename`.
+
+* `ui`: Shows the file picker dialog with `filename` pre-completed, `true` by default. Set to
+  `false` to load `filename` directly without user confirmation.
+* `filename`: A path to a supported palette or file to extract a palette from, optional.
+* `preset`: The name of a palette preset, `"default"` resets the palette to default. If set, `filename` is ignored.
+
diff --git a/api/command/MaskByColor.md b/api/command/MaskByColor.md
@@ -0,0 +1,17 @@
+# MaskByColor
+
+```lua
+app.command.MaskByColor {
+  ui=true,
+  color=Color,
+  tolerance=int,
+  mode=SelectionMode
+}
+```
+
+Creates a new selection by color
+
+* `ui`: Shows the dialog on the screen, `true` by default. Set to `false` to select automatically.
+* `color`: The [color](../color.md#color) to mask by. Defaults to the current foreground color.
+* `tolerance`: The maximum allowed difference between `color` and the pixel to be selected, from `0` to `255`. Defaults to `0`
+* `mode`: [SelectionMode](../selectionmode.md)
diff --git a/api/command/ModifySelection.md b/api/command/ModifySelection.md
@@ -0,0 +1,17 @@
+# ModifySelection
+
+```lua
+app.command.ModifySelection {
+  ui=true,
+  modifier=string,
+  quantity=int,
+  brush=string
+}
+```
+
+Modifies the active selection.
+
+* `ui`: Shows the selection modification dialog on screen, `true` by default. Set to `false` to modify automatically.
+* `modifier`: One of `"border"`, `"expand"`, or `"contract"`.
+* `quantity`: The pixel amount to modify the selection by. *Note*: Will attempt to show the UI if set to `0`.
+* `brush`: One of `"circle"`, or `"square"`.
diff --git a/api/command/MoveMask.md b/api/command/MoveMask.md
@@ -1,7 +1,5 @@
 # MoveMask
 
-Moves the selection boundaries or its content (pixels).
-
 ```lua
 app.command.MoveMask {
   target='boundaries' | 'content',
@@ -12,27 +10,15 @@ app.command.MoveMask {
 }
 ```
 
+Moves the selection boundaries or its content (pixels).
+
 * `target` (string): must be
-  * `'boundaries'` to modify selection boundaries onlyor
+  * `'boundaries'` to modify selection boundaries only or
   * `'content'` to modify the selection content ([active cel](../app.md#appcel) pixels)
 * `wrap`: `true` or `false`, when true it does the *Edit > Shift* effect,
   were pixels from one side in will appear from the other side (so the
   content is shifted and pixels wrapped, so the selection boundaries
   is not moved at all, only pixels inside it)
-* `direction` (string): the selection will be moved to a specific direction:
-  * `'left'`
-  * `'right'`
-  * `'up'`
-  * `'down'`
-* `units` (string): must be one of these options (generally `pixel` is
-  enough for scripts, and other options are just for UI):
-  * `'pixel'`
-  * `'tile-width'`
-  * `'tile-height'`
-  * `'zoomed-pixel'`
-  * `'zoomed-tile-width'`
-  * `'zoomed-tile-height'`
-  * `'viewport-width'`
-  * `'viewport-height'`
-* `quantity`: the number of `pixel`s, or `tile-width`s, etc. to move
-  the selection to the given `direction` depending on the `units`
+* `direction`: The selection will be moved to a specific direction, can be `"left"`, `"right"`, `"up"` or `"down"`.
+`units`: The unit to use for `quantity`. Can be `"pixel"`, `"tile-width"`, `"tile-height"` `"zoomed-pixel"`, `"zoomed-tile-width"`, `"zoomed-tile-height"`, `"viewport-width"`, `"viewport-height"`.
+* `quantity`: the number of `pixel`s, or `tile-width`s, etc. to move the selection to the given `direction` depending on the `units`.
diff --git a/api/command/NewFrame.md b/api/command/NewFrame.md
@@ -0,0 +1,11 @@
+# NewFrame
+
+```lua
+app.command.NewFrame {
+    content="current" | "empty" | "cel" | "celblock" | "celcopies" | "cellinked"
+}
+```
+
+Creates a new frame.
+
+* `content`: The contents of the frame, defaults to `"current"`. One of `"current"`, `"empty"`, `"cel"`, `"celcopies"`, `"cellinked"`
diff --git a/api/command/OpenFile.md b/api/command/OpenFile.md
@@ -0,0 +1,20 @@
+# OpenFile
+
+```lua
+app.command.OpenFile {
+  ui=true,
+  filename=string,
+  folder=string,
+  repeat_checkbox=bool,
+  oneframe=bool,
+  sequence=string
+}
+```
+
+Opens a file, or sequence of files (UI only through the dialog)
+
+* `ui`: Shows the file opening dialog, `true` by default.
+* `filename`: The filename to open
+* `folder`: Folder to pre-fill the dialog (with UI only)
+* `repeat_checkbox`: Whether the file renaming actions for sequences will show a dialogue or use the given `sequence` (UI only)
+* `sequence`: One of `"ask"`, `"yes"`, or `"no"`.
diff --git a/api/command/PaletteSize.md b/api/command/PaletteSize.md
@@ -0,0 +1,13 @@
+# PaletteSize
+
+```lua
+app.command.PaletteSize {
+  ui=true,
+  size=int
+}
+```
+
+Changes the palette size
+
+* `ui`: Shows the palette resizing dialog, defaults to `true`.
+* `size`: The new palette size. *Note*: Will attempt to show the UI if set to `0`.
diff --git a/api/command/Rotate.md b/api/command/Rotate.md
diff --git a/api/command/SaveMask.md b/api/command/SaveMask.md
diff --git a/api/command/SavePalette.md b/api/command/SavePalette.md
diff --git a/api/command/Scroll.md b/api/command/Scroll.md
diff --git a/api/command/SetLoopSection.md b/api/command/SetLoopSection.md
diff --git a/api/command/Zoom.md b/api/command/Zoom.md

Original file line number	Diff line number	Diff line change
`@@ -7,10 +7,10 @@ app.command.AddColor {`
`7`	`7`	`}`
`8`	`8`	```
`9`	`9`
`10`		`-Adds a new color into the palette.`
	`10`	`+Adds a new color to the palette.`
`11`	`11`
`12`	`12`	* `source`: Can be `"fg"`, `"bg"`, or `"color"` (default). To add the foreground, background, or a specific color respectively.
`13`		-* `color`: A [Color](../color.md#color) instance to add too the palette.
	`13`	+* `color`: A [Color](../color.md#color) instance to add to the palette.
`14`	`14`
`15`	`15`	`## Example`
`16`	`16`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`	`app.command.ConvolutionMatrix {`
`5`	`5`	`ui=true,`
`6`	`6`	`channels=FilterChannels...,`
`7`		`- tiledMode=none,`
	`7`	`+ tiledMode=string,`
`8`	`8`	`fromResource=string`
`9`	`9`	`}`
`10`	`10`	```