Aseprite Sprite

An Aseprite file (.aseprite / .ase) played as Aseprite does: tags, directions, repeats, frame durations; layers on / off, slices and user data for scripts. Saving in Aseprite updates it live.

Type: AsepriteNode · Category: Animation & Effects · Also found as: aseprite, ase

Properties

Property	Type	Default	Description
file	string	""	The Aseprite file (.aseprite / .ase, project-relative). Saving it in Aseprite updates the node, in the editor and in a running game.
animation	string	""	The tag played (its direction and repeat count as set in Aseprite); empty = every frame in order.
autoplay	boolean	true	Start the animation when the node becomes ready.
loop	boolean	true	Tags without a repeat count loop; off: they play once.
speed	number	1	Playback speed (1 = the frame durations set in Aseprite). Range 0 to 5.
frame	integer	0	The frame shown (0-based): where playing starts, or where it stopped. Range 0 to 0.
hideLayers	string	""	Layers not drawn (names, comma separated; a group hides its layers).
showLayers	string	""	Layers hidden in the file but drawn anyway (names, comma separated).
pivotSlice	string	""	A slice with a pivot (set in Aseprite): the node’s origin follows it, frame by frame. Empty = the node’s pivot.
tint	color	#ffffffff	Multiplies the sprite’s colours.

Plus the common properties every node has.

Lua methods

Call them on the node (self.node in its script, or self.node:get_node("path")). Every node also has the Node methods.

AsepriteNode:connect(event, handler)

Connects a handler to one of this node’s events: animation_finished (A non-looping animation ended (Aseprite: a tag’s repeats are done)), animation_looped (An Aseprite tag started again (a repeat or a ping-pong turn)), frame_changed (The Aseprite node shows another frame (0-based)); the tree events; custom ones.

self.node:connect("animation_finished", function(value, source) Log.info("animation_finished") end)

• event AsepriteNodeEvent|string
• handler fun(value: any, source: AsepriteNode)

Returns integer id Connection id for disconnect

AsepriteNode:get_property(path)

Reads an Inspector property by its path (vectors and colours as tables); “script.” reads a field of the node’s script.

local value = self.node:get_property("file")

• path AsepriteNodeProperty|string

Returns any

AsepriteNode:set_property(path, value, y)

Sets an Inspector property by its path: vectors as {x, y} or x, y; colours as {r, g, b[, a]} 0..1 or “#rrggbb[aa]”; enums by name; “script.” a field of the node’s script.

self.node:set_property("file", "text")

• path AsepriteNodeProperty|string
• value any
• y? number

AsepriteNode:aseprite_play(tag)

Plays a tag (its direction and repeats as set in Aseprite) from its first frame; nil / “” = every frame. No argument: the node’s Animation.

sprite:aseprite_play("run")

• tag? string

AsepriteNode:aseprite_stop()

Stops on the current frame.

sprite:aseprite_stop()

AsepriteNode:aseprite_resume()

Goes on from where it stopped.

if paused_menu_closed then sprite:aseprite_resume() end

AsepriteNode:aseprite_is_playing()

A tag is playing (false after its repeats are done, or stopped).

if not sprite:aseprite_is_playing() then sprite:aseprite_play("idle") end

Returns boolean

AsepriteNode:aseprite_frame()

The frame shown (0-based).

if sprite:aseprite_frame() == 3 then shoot() end

Returns integer

AsepriteNode:aseprite_set_frame(frame)

Shows a frame (0-based); a playing tag goes on from it.

sprite:aseprite_set_frame(0)

• frame integer

AsepriteNode:aseprite_info()

The file: size, frame durations, tags, layers, the sprite’s user data.

for _, tag in ipairs(sprite:aseprite_info().tags) do print(tag.name, tag.direction) end

Returns AsepriteInfo?

AsepriteNode:aseprite_slice(name, frame)

A slice in a frame (default: the frame shown) - hitboxes, spawn points, 9-patch panels drawn in Aseprite. nil if it isn’t there.

local hit = sprite:aseprite_slice("hitbox")

• name string
• frame? integer

Returns AsepriteSlice?

AsepriteNode:aseprite_layer_data(layer)

A layer’s user data (text, colour, properties set in Aseprite’s layer properties).

local damage = sprite:aseprite_layer_data("Weapon").properties.damage

• layer string

Returns AsepriteUserData?

AsepriteNode:aseprite_cel_data(layer, frame)

A cel’s user data (a layer in a frame; default: the frame shown).

if sprite:aseprite_cel_data("Body").properties.footstep then play_step() end

• layer string
• frame? integer

Returns AsepriteUserData?

AsepriteNode:aseprite_set_layer_visible(layer, visible)

Shows or hides a layer (by name; a group: its layers) - outfits, equipment, damage.

sprite:aseprite_set_layer_visible("Helmet", has_helmet)

• layer string
• visible boolean

In a scene file

{
  "type": "AsepriteNode",
  "name": "AsepriteSprite",
  "position": [
    0,
    0
  ],
  "properties": {
    "file": "",
    "animation": "",
    "autoplay": true
  }
}