lua_animation_api.adoc

Lua animation API

Each Lua script needs to define an update(value) function. It will be called each frame of the animation with a different value parameter.

If you need to perform some calculation only once, when the animation is first started, consider using the init(value) function as an optimization.

get_canvas_width() / get_canvas_height()

Returns the canvas width or height in pixels.

local canvas_width = get_canvas_width()
local canvas_height = get_canvas_height()
print("canvas size: " .. canvas_width .. "x" .. canvas_height)

get_texture_width() / get_texture_height()

Returns the sprite texture width or height in pixels.

local texture_width = get_texture_width()
local texture_height = get_texture_height()
print("texture size: " .. texture_width .. "x" .. texture_height)

get_width() / get_height()

Returns the sprite width or height in pixels.

local width = get_width()
local height = get_height()
print("sprite size: " .. width .. "x" .. height)

get_position()

Returns the position of the sprite in pixels as a table with the x and the y fields.

local position = get_position()
print("position x: " .. position.x .. " y: " .. position.y)

get_x() / get_y()

Returns the x or y component of the position of the sprite in pixels.

local x = get_x()
local y = get_y()
print("position x: " .. x .. " y: " .. y)

get_rotation()

Returns the rotation of the sprite in degrees.

local rotation = get_rotation()
print("rotation: " .. rotation)

get_scale()

Returns the scale of the sprite as a table with the x and the y fields.

local scale = get_scale()
print("scale x: " .. scale.x .. " y: " .. scale.y)

get_scale_x() / get_scale_y()

Returns the x or y component of the scale of the sprite.

local scale_x = get_scale_x()
local scale_y = get_scale_y()
print("scale x: " .. scale_x .. " y: " .. scale_y)

get_anchor()

Returns the anchor point of the sprite in pixels as a table with the x and the y fields.

local anchor = get_anchor()
print("anchor x: " .. anchor.x .. " y: " .. anchor.y)

get_anchor_x() / get_anchor_y()

Returns the x or y component of the anchor point of the sprite.

local anchor_x = get_anchor_x()
local anchor_y = get_anchor_y()
print("anchor x: " .. anchor_x .. " y: " .. anchor_y)

get_color()

Returns the color of the sprite as a table with the r, g, b and a fields for the normalized values of the red, green, blue and alpha channels.

local color = get_color()
print(string.format("color: #%X%X%X%X", math.floor(color.r * 255 + 0.5), math.floor(color.g * 255 + 0.5), math.floor(color.b * 255 + 0.5), math.floor(color.a * 255 + 0.5)))

get_texrect()

Returns the texture rectangle of the sprite as a table with the x, y, w and h fields for the position, the width, and the height of the rectangle.

local rect = get_texrect()
print("texrect x: " .. rect.x .. " y: " .. rect.y .. " w: " .. rect.w .. " h: " .. rect.h)

get_flipped_x() / get_flipped_y()

Returns the value of the horizontal or vertical flipping flag of the sprite.

local is_hflipped = get_flipped_x()
local is_vflipped = get_flipped_y()
print("flipped h: " .. (is_hflipped and 'true' or 'false') .. " v: " .. (is_vflipped and 'true' or 'false'))

get_rgb_blending() / get_alpha_blending()

Returns the current blending preset value for the RGB or alpha channels of the sprite. It can be one of the members of the blending_preset table: DISABLED, ALPHA, PREMULTIPLIED_ALPHA, ADDITIVE, or MULTIPLY.

• DISABLED: source factor is GL_ONE, destination factor is GL_ZERO.

• ALPHA: source factor is GL_SRC_ALPHA, destination factor is GL_ONE_MINUS_SRC_ALPHA.

• PREMULTIPLIED_ALPHA: source factor is GL_ONE, destination factor is GL_ONE_MINUS_SRC_ALPHA.

• ADDITIVE: source factor is GL_SRC_ALPHA, destination factor is GL_ONE.

• MULTIPLY: source factor is GL_DST_COLOR, destination factor is GL_ZERO.

local blending = get_rgb_blending()

local blending_string = "UNKNOWN"
if blending == blending_preset.DISABLED then
	blending_string = "DISABLED"
elseif blending == blending_preset.ALPHA then
	blending_string = "ALPHA"
elseif blending == blending_preset.PREMULTIPLIED_ALPHA then
	blending_string = "PREMULTIPLIED_ALPHA"
elseif blending == blending_preset.ADDITIVE then
	blending_string = "ADDITIVE"
elseif blending == blending_preset.MULTIPLY then
	blending_string = "MULTIPLY"
end

print("blending: " .. blending_string)

get_num_vertices()

Returns the number of vertices of the sprite grid.

local num_vertices = get_num_vertices()
print("number of vertices: " .. num_vertices)

get_vertices()

Returns all the vertices of the sprite grid as an array of tables with the x, y, u, and v fields for the positions and the texture coordinates.

local vertices = get_vertices()
-- Print the position and texture coordinates of the first four vertices
for i = 1, 4 do
	print(string.format("vertex #%d x: %f y: %f u: %f v: %f", i, vertices[i].x, vertices[i].y, vertices[i].u, vertices[i].v))
end

get_vertices_xy()

Returns all the vertices of the sprite grid as an array of tables with the x and y fields for the positions.

local vertices_xy = get_vertices_xy()
-- Print the position of the first four vertices
for i = 1, 4 do
	print(string.format("vertex #%d x: %f y: %f", i, vertices_xy[i].x, vertices_xy[i].y))
end

get_vertices_uv()

Returns all the vertices of the sprite grid as an array of tables with the u and v fields for the texture coordinates.

local vertices_uv = get_vertices_uv()
-- Print the texture coordinates of the first four vertices
for i = 1, 4 do
	print(string.format("vertex #%d u: %f v: %f", i, vertices_uv[i].u, vertices_uv[i].v))
end

get_vertices_x() / get_vertices_y() / get_vertices_u() / get_vertices_v()

Returns all the vertices of the sprite grid as an array of x, y, u, or v components of the positions or texture coordinates.

local vertices_x = get_vertices_x()
local vertices_y = get_vertices_y()
local vertices_u = get_vertices_u()
local vertices_v = get_vertices_v()
-- Print the texture coordinates of the first four vertices
for i = 1, 4 do
	print(string.format("vertex #%d x: %f y: %f u: %f v: %f", i, vertices_x[i], vertices_y[i], vertices_u[i], vertices_v[i]))
end

set_position()

Sets the position of the sprite in pixels through a table with the x and the y fields.

new_position = { x = 0, y = 0 }
set_position(new_position)

set_x() / set_y()

Sets the x or y component of the position of the sprite in pixels.

set_x(0)
set_y(0)

set_rotation()

Sets the rotation of the sprite in degrees.

set_rotation(0)

set_scale()

Sets the scale of the sprite through a table with the x and the y fields.

new_scale = { x = 1, y = 1 }
set_scale(new_scale)

set_scale_x() / set_scale_y()

Sets the x or y component of the scale of the sprite.

set_scale_x(1)
set_scale_y(1)

set_anchor()

Sets the anchor point of the sprite in pixels with one rgument: as a table with the x and the y fields.

new_anchor = { x = 0, y = 0 }
set_anchor(new_anchor)

set_anchor_x() / set_anchor_y()

Sets the x or y component of the anchor point of the sprite.

set_anchor_x(0)
set_anchor_y(0)

set_color()

Sets the color of the sprite through a table with the r, g, b and a fields for the normalized values of the red, green, blue and alpha channels.

new_color = { r = 1.0, g = 1.0, b = 1.0, a = 1.0}
set_color(new_color)

set_texrect()

Sets the texture rectangle of the sprite through a table with the x, y, w and h fields for the position, the width, and the height of the rectangle.

new_rect = { x = 0, y = 0, w = get_texture_width(), h = get_texture_height()}
set_texrect(new_rect)

set_flipped_x() / set_flipped_y()

Sets the value of the horizontal or vertical flipping flag of the sprite.

set_flipped_x(false)
set_flipped_y(false)

set_rgb_blending() / set_alpha_blending()

Sets the blending preset value for the RGB or alpha channels of the sprite. It can be one of the members of the blending_preset table: DISABLED, ALPHA, PREMULTIPLIED_ALPHA, ADDITIVE, or MULTIPLY.

set_rgb_blending(blending_preset.ALPHA)

set_vertices()

Sets all the vertices of the sprite grid with one argument: an array of tables with the x, y, u, and v fields for the positions and the texture coordinates.

local vertices = get_vertices()

-- Change the position and texture coordinate of the first vertex
vertices[1].x = 0
vertices[1].y = 0
vertices[1].u = 0
vertices[1].v = 0

set_vertices(vertices)

set_vertices_xy()

Sets all the vertices of the sprite grid with one argument: an array of tables with the x and y fields for the positions.

local vertices_xy = get_vertices_xy()

-- Change the position of the first vertex
vertices_xy[1].x = 0
vertices_xy[1].y = 0

set_vertices_xy(vertices_xy)

set_vertices_uv()

Sets all the vertices of the sprite grid with one argument: an array of tables with the u and v fields for the texture coordinates.

local vertices_uv = get_vertices_uv()

-- Change the texture coordinate of the first vertex
vertices_uv[1].u = 0
vertices_uv[1].v = 0

set_vertices_uv(vertices_uv)

set_vertices_x()

Sets all the vertices of the sprite grid with one argument: an array of x components of the positions.

local vertices_x = get_vertices_x()

-- Change the horizontal position of the first vertex
vertices_x[1] = 0

set_vertices_x(vertices_x)

set_vertices_y()

Sets all the vertices of the sprite grid with one argument: an array of y components of the positions.

local vertices_y = get_vertices_y()

-- Change the vertical position of the first vertex
vertices_y[1] = 0

set_vertices_y(vertices_y)

set_vertices_u()

Sets all the vertices of the sprite grid with one argument: an array of u components of the texture coordinates.

local vertices_u = get_vertices_u()

-- Change the horizontal texture coordinate of the first vertex
vertices_u[1] = 0

set_vertices_u(vertices_u)

set_vertices_v()

Sets all the vertices of the sprite grid with one argument: an array of v components of the texture coordinates.

local vertices_v = get_vertices_v()

-- Change the vertical texture coordinate of the first vertex
vertices_v[1] = 0

set_vertices_v(vertices_v)