DOCSEARCHbyAlgolia
Submit Docs

anim8 Documentation

repository·master·Indexed 21 days ago

https://github.com/kikito/anim8

A lightweight animation library for the LÖVE (Love2D) game engine. anim8 simplifies sprite animation by separating the process into grid creation for defining frame locations via anim8.newGrid and animation creation for defining frame sequences and timing via anim8.newAnimation.

Tokens
1.7K
Snippets
6
Records
7
Agent score
26%

What's inside anim8

  1. How grids and animations work together

    master

    anim8 uses a two-step process to build animations:

    1. Create a Grid: A Grid object is used to divide a spritesheet into individual frames (Quads). It handles the math of calculating where each frame is located based on dimensions and borders.
    2. Create an Animation: An Animation object is created by passing it a collection of frames (retrieved from a Grid) and timing information.

    This separation allows you to reuse the same Grid to create multiple different animations (e.g., a 'walk' animation and an 'idle' animation) from the same spritesheet.

    local anim8 = require 'anim8'
local image = love.graphics.newImage('path/to/image.png')

-- 1. Create the grid
local g = anim8.newGrid(32, 32, image:getWidth(), image:getHeight())

-- 2. Create the animation using frames from the grid
local animation = anim8.newAnimation(g('1-8', 1), 0.1)

  2. Install anim8

    master

    To use anim8, copy the anim8.lua file into your project directory and use the standard Lua require function to load it.

    local anim8 = require 'anim8'

  3. Create an Animation with `anim8.newAnimation`

    master

    The newAnimation function creates an animation object from a set of frames and timing data.

    Syntax: anim8.newAnimation(frames, durations, [onLoop])

    Parameters:

    • frames (table): An array of frames (Quads). Usually obtained from a Grid.
    • durations (number | table):
      • If a number: Every frame has this duration (in seconds).
      • If a table: Allows per-frame timing. You can use indices {0.1, 0.5} or ranges {[ '3-5' ] = 0.2}.
    • onLoop (function | string, optional): Called when the animation loops.
      • If a string 'pauseAtEnd': The animation loops once and then stops on the last frame.
      • If a function: Receives (animationInstance, loopCount) as arguments.
    -- Animation with uniform duration
local animation = anim8.newAnimation(g('1-8', 1), 0.1)

-- Animation with custom frame durations
local animation = anim8.newAnimation(g('1-8', 1), { [ '1-3' ] = 0.1, [ '4-8' ] = 0.5 })

-- Animation that pauses at the end
local animation = anim8.newAnimation(g('1-8', 1), 0.1, 'pauseAtEnd')

  4. Control an Animation

    master

    Use these methods to manage the playback and state of an Animation instance.

    | Method | Description | |---|---|animation:update(dt)| Advances the animation by dt seconds. Call this in love.update.| |animation:draw(image, x, y, ...)| Draws the current frame. Parameters match love.graphics.draw. Handles flips automatically.|animation:gotoFrame(frame)| Jumps to a specific frame (1-indexed).| |animation:pause()| Stops the animation from updating.|animation:resume()| Resumes a paused animation.|animation:clone()| Returns a new animation instance identical to the current one, but reset to frame 1.|animation:flipH()| Flips the animation horizontally (returns the animation instance).|animation:flipV()| Flips the animation vertically (returns the animation instance).|animation:pauseAtEnd()| Jumps to the last frame and pauses.|animation:pauseAtStart()| Jumps to the first frame and pauses.|animation:getDimensions()| Returns the width and height of the current frame.|

  5. Use `animation:getFrameInfo` with SpriteBatches

    master

    If you are using love.graphics.newSpriteBatch, you can use animation:getFrameInfo to retrieve the exact parameters needed to add or update a sprite in the batch. This ensures that flips and offsets are correctly calculated for the batch.

    Syntax: animation:getFrameInfo(x, y, r, sx, sy, ox, oy, kx, ky)

    Returns: frame, x, y, r, sx, sy, ox, oy, kx, ky (where frame is the current Quad).

    -- Adding a frame to a SpriteBatch
local info = animation:getFrameInfo(x, y, r, sx, sy, ox, oy, kx, ky)
local id = spriteBatch:add(info)

-- Updating an existing frame in a SpriteBatch
spriteBatch:set(id, animation:getFrameInfo(x, y, r, sx, sy, ox, oy, kx, ky))

  6. Create a Grid with `anim8.newGrid`

    master

    The newGrid function creates a grid used to extract frames from an image.

    Syntax: anim8.newGrid(frameWidth, frameHeight, imageWidth, imageHeight, [left], [top], [border])

    Parameters:

    • frameWidth (number): Width of an individual animation frame.
    • frameHeight (number): Height of an individual animation frame.
    • imageWidth (number): Total width of the source image.
    • imageHeight (number): Total height of the source image.
    • left (number, optional): The X coordinate of the grid's origin in the image. Defaults to 0.
    • top (number, optional): The Y coordinate of the grid's origin in the image. Defaults to 0.
    • border (number, optional): The size of the gap/border between frames in the image. Defaults to 0.
    -- Example: 32x32 frames in a 1024x768 image with a 1px border
local gs = anim8.newGrid(32, 32, 1024, 768, 0, 0, 1)

  7. Get frames from a Grid

    master

    A Grid can be called like a function to retrieve one or more frames (Quads). This is a shortcut for the Grid:getFrames(...) method.

    Supported Formats:

    • Coordinate Pairs: grid(col, row, col, row, ...) returns specific frames. Example: g(1, 1, 1, 2) returns the first and second frames of the first column.
    • String Ranges:
      • To fetch a row: grid('range', rowNumber). Example: g('1-3', 2) gets frames 1 through 3 in row 2.
      • To fetch a column: grid(columnNumber, 'range'). Example: g(1, '1-3') gets frames 1 through 3 in column 1.
    • Mixed: You can combine formats. Example: g(1, 4, 1, '1-3') gets the frame at (1,4) plus the first three frames of column 1.
    -- Using the grid as a function to get frames
local frames = g('1-7', 1)

-- Getting frames in reverse for a 'submersion' effect
local frames = g('1-7', 1, '6-2', 1)