Skip to content

sprite.md

Latest commit

 

History

History
625 lines (446 loc) · 14.7 KB

sprite.md

File metadata and controls

625 lines (446 loc) · 14.7 KB

Sprite

Sprite()

local sprite = Sprite(width, height)
local sprite = Sprite(width, height, colorMode)
local sprite = Sprite(spec)
local sprite = Sprite(otherSprite)
local sprite = Sprite{ fromFile=string }
local sprite = Sprite{ fromFile=string, oneFrame=true }

Creates a new sprite with the given width and height. The color mode is optional, RGB by default.

The spec parameter is an image specification object.

If otherSprite is given (other Sprite object), the sprite is duplicated.

If fromFile is given, it indicates a file name (a string) and it's like opening a new document with app.open().

When loading from a file, setting oneFrame to true will load with only the first animation frame.

Sprite.width

local w = sprite.width
sprite.width = w

Returns or changes the sprite width. Use Sprite:resize if you want to change the sprite size resizing layers, images, etc.

Sprite.height

local h = sprite.height
sprite.height = h

Returns or changes the sprite height. Use Sprite:resize if you want to change the sprite size resizing layers, images, etc.

Sprite.bounds

local rectangle = sprite.bounds

Returns the bounds of the sprite as a rectangle in the position 0,0. This is like calling Rectangle{ x=0, y=0, width=sprite.width, height=sprite.height }.

Sprite.gridBounds

local rectangle = sprite.gridBounds
sprite.gridBounds = rectangle

Gets or sets the bounds of the sprite grid as a rectangle. By default this is 16x16 (with origin in 0,0) but the default value can be changed from Edit > Preferences > Grid.

Sprite.pixelRatio

local size = sprite.pixelRatio
sprite.pixelRatio = size

Gets or sets the pixel ratio of the sprite as a size.

Sprite.selection

local selection = sprite.selection
sprite.selection = newSelection

Gets or sets the active sprite selection. This property is an instance of the Selection class to manipulate the set of selected pixels in the canvas.

Keep in mind that local selection = sprite.selection will be a reference to the Sprite's selection, and will update when the Sprite's selection is changed or removed. To clone the selection, you can do the following instead:

local selection = Selection()
selection:add(sprite.selection)

Sprite.filename

local name = sprite.filename
sprite.filename = newName

Gets or sets the name of the file from where this sprite was loaded or saved. Or an empty string if this is a new sprite without an associated file.

Sprite.id

local id = sprite.id

Returns the id of this sprite, as an integer.

Sprite.isModified

local modified = sprite.isModified

Returns true if the sprite is modified compared to the latest saved state on disk.

Sprite.colorSpace

local colorspace = sprite.colorSpace
sprite.colorSpace = colorspace

Gets or sets the color space of this sprite. Setting works the same as using Sprite:assignColorSpace().

Sprite.colorMode

local colormode = sprite.colormode

Returns the color mode of this sprite.

Sprite.spec

local spec = sprite.spec

Returns the specification for image in this sprite.

Sprite.undoHistory.undoSteps

local undosteps = sprite.undoHistory.undoSteps

Returns the amount of undo steps (steps before the current step), as an integer.

Sprite.undoHistory.redoSteps

local redosteps = sprite.undoHistory.redoSteps

Returns the amount of redo steps (steps after the current step), as an integer.

Sprite.frames

for i,frame in ipairs(s.frames) do
  -- ...
end
for i = 1,#s.frames do
  -- s.frames[i]
end

An array of frames.

Sprite.palettes

local palette = sprite.palettes[1]

An array of palettes. In most cases, it only contains one palette (sprite.palettes[1]), except in a very specific case.

In the event that two or more indexed numbered files (eg. spr_01.png, spr_02.png, spr_03.png etc.) are opened as a sequence, each frame would have its own palette. This only occurs when there are at least two different indexed palettes, so the indexed palette for the spr_01.png frame would have different index-to-color mapping than the indexed palette for the spr_02.png (same with spr_03.png), hence the need for three sprite palettes. If two images/frames have the same indexed palette, they will share (so if spr_01.png and spr_02.png have the same palette, but spr_03.png has a different one, there would be 2 sprite palettes).

There is no proper UI to support multiple palettes at the moment, but in a future we want to create an easy way to create color cycling animations.

Sprite.layers

for i,layer in ipairs(s.layers) do
  -- ...
end
for i = 1,#s.layers do
  -- s.layers[i]
end

An array of layers.

Sprite.cels

for i,cel in ipairs(s.cels) do
  -- ...
end
for i = 1,#s.cels do
  -- s.cels[i]
end

An array of cels.

Sprite.tags

for i,tag in ipairs(s.tags) do
  -- ...
end
for i = 1,#s.tags do
  -- s.tags[i]
end

An array of tags.

Sprite.slices

for i,slice in ipairs(s.slices) do
  -- ...
end
for i = 1,#s.slices do
  -- s.slices[i]
end

An array of slices.

Sprite.tilesets

for i,tileset in ipairs(s.tilesets) do
  -- ...
end
for i = 1,#s.tilesets do
  -- s.tilesets[i]
end

An array of tilesets.

Sprite.backgroundLayer

Returns the background layer a layer object or nil if the sprite doesn't contain a background layer.

Sprite.transparentColor

local number = sprite.transparentColor
sprite.transparentColor = number

The transparent color is an intenger that specifies what index (0 by default) is the transparent color in transparent layers on indexed sprites.

Sprite.color

local color = sprite.color
sprite.color = color

Gets or sets the user-defined color of this sprite. This color is used to display the tab in the main window of this sprite.

Sprite.data

local data = sprite.data
sprite.data = data

Gets or sets the user-defined data related to this sprite (a text string).

Sprite.properties

Access user-defined and extension-defined properties of this sprite.

Sprite:resize()

sprite:resize(width, height)
sprite:resize(size)

Resize the sprite (and all frames/cels) to the given dimensions. See Size class.

Sprite:crop()

sprite:crop(x, y, width, height)
sprite:crop(rectangle)

Crops the sprite to the given dimensions. See the Rectangle class.

Sprite:saveAs()

sprite:saveAs(filename)

Saves the sprite to the given file and marks the sprite as saved so closing it won't ask to save changes.

Sprite:saveCopyAs()

sprite:saveCopyAs(filename)

Saves a copy of the sprite in the given file but doesn't change the saved state of the sprite, if the sprite is modified and then try to close it, the user will be asked to save changes.

Sprite:close()

sprite:close()

Closes the sprite. This doesn't ask the user to save changes. If you want to do the classic File > Close where the user is asking to save changes, you can use app.command.CloseFile().

Sprite:loadPalette()

sprite:loadPalette(filename)

Sets the sprite palette loading it from the given file.

The same can be achieved using Palette{ fromFile }:

sprite:setPalette(Palette{ fromFile=filename })

Sprite:setPalette()

sprite:setPalette(palette)

Changes the sprite palette.

Sprite:assignColorSpace()

local colorSpace = ColorSpace{ sRGB=true }
sprite:assignColorSpace(colorSpace)

Assign a new color space to the sprite without modifying the sprite pixels.

Sprite:convertColorSpace()

local colorSpace = ColorSpace{ sRGB=true }
sprite:convertColorSpace(colorSpace)

Converts all the sprite pixels to a new color space so the image looks the same as in the previous color space (all pixels will be adjusted to the new color space).

Sprite:newLayer()

local layer = sprite:newLayer()

Creates a new layer at the top of the layers stack.

Sprite:newGroup()

local layerGroup = sprite:newGroup()

Creates a new empty layer group at the top of the layers stack.

Sprite:deleteLayer()

sprite:deleteLayer(layer)
sprite:deleteLayer(layerName)

Deletes the given layer or the layer with the given layerName (a string).

Sprite:newFrame()

local frame = sprite:newFrame(frame)
local frame = sprite:newFrame(frameNumber)

Creates a copy of the given frame object or frame number and returns a Frame that points to the newly created frame in frameNumber position.

Sprite:newEmptyFrame()

Creates a new empty frame in the given frameNumber (an integer) and returns the new frame.

Sprite:deleteFrame()

sprite:deleteFrame(frame)

Sprite:newCel()

cel = sprite:newCel(layer, frame)
cel = sprite:newCel(layer, frame, image, position)

Creates a new cel in the given layer and frame number. If the image is not specified, a new image will be created with the size of the sprite canvas. The position is a point to locate the image.

Sprite:deleteCel()

sprite:deleteCel(cel)
sprite:deleteCel(layer, frame)

Deletes the given cel. If the cel is from a transparent layer, the cel is completely deleted, but if the cel is from a background layer, the cel will be delete with the background color.

Sprite:newTag()

local tag = sprite:newTag(fromFrameNumber, toFrameNumber)

Creates a new tag in the given frame range and with the given name.

Sprite:deleteTag()

sprite:deleteTag(tag)
sprite:deleteTag(tagName)

Deletes the given tag.

Sprite:newSlice()

local slice = sprite:newSlice()
local slice = sprite:newSlice(Rectangle)

Returns a new slice.

Sprite:deleteSlice()

sprite:deleteSlice(slice)
sprite:deleteSlice(sliceName)

Deletes the given slice.

Sprite:newTileset()

local tileset = sprite:newTileset()
local tileset = sprite:newTileset(Grid)
local tileset = sprite:newTileset(Rectangle)
local tileset = sprite:newTileset(Grid, numTiles)
local tileset = sprite:newTileset(Rectangle, numTiles)
local tileset = sprite:newTileset(anotherTileset)

Returns a new tileset and adds it to the sprite's tilesets.

If no parameters are given, the resulting tileset will have just one empty tile and a tile size equal to the active sprite grid size.

If Grid or Rectangle is specified it is used to set the resulting tileset's origin and tile size.

numTiles specifies the number of tiles we want the tileset to contain initially.

If another tileset is passed as the only parameter, the result is a duplicate of it. Take into consideration that the passed tileset cannot belong to another sprite.

Sprite:deleteTileset()

sprite:deleteTileset(tileset)
sprite:deleteTileset(tilesetIndex)

Deletes the given tileset from the sprite's tilesets.

Sprite:newTile()

local tile = sprite:newTile(tileset [, tileIndex])

Inserts an empty tile into the given tileset at a given tileIndex. If tileIndex is not provided, the new tile is added to the end of the tileset. This method generates undo information, so you could use it as an individual operation or in a transaction.

Sprite:deleteTile()

local tile = tileset:tile(tileIndex)
Sprite:deleteTile(tile)
Sprite:deleteTile(tileset, tileIndex)

Removes a tile from a tileset. This method generates undo information, so you could use it as an individual operation or in a transaction.

Sprite:flatten()

sprite:flatten()

Flatten all layers of the sprite into one layer. It's like calling app.commands.FlattenLayers().

Sprite.events

Returns the Events object to associate functions that can act like listeners of specific Sprite events. E.g.

sprite.events:on('change',
  function(ev)
    print('The sprite has changed')
  end)

A special ev argument can be sent to the listener. Which generally is a table, but it can be nil for older version of Aseprite or events that don't support it.

Available events for a Sprite:

  • 'change': When the sprite content changes because an action is performed on it (also called when those actions are undone/redone). Since Aseprite v1.2.41, you can access ev.fromUndo property which is true if the change came from a undo/redo/undo history event (and not from a direct user change in the sprite).
  • 'filenamechange': When the filename associated to a sprite changes.
  • 'layerblendmode': The blend mode of a layer is changed.
  • 'layername': The name of a layer is changed.
  • 'layeropacity': The opacity of a layer is changed.
  • 'layervisibility': The visibility of a layer is changed.

Sprite.tileManagementPlugin

local id = sprite.tileManagementPlugin
sprite.tileManagementPlugin = newId

Special property to disable Aseprite tile management UI and use an external plugin to handle tilesets and tilemaps in this sprite.

This property is used by the Attachment-System plugin, but any extension can create a totally customized way to handle tiles (and disable the standard UI to avoid conflicts).

Warning: If a sprite has this property set, another plugin shouldn't change it, because it might break the tilesets/tilemaps structure.