### Running Busted Specs for anim8 in Shell

Source: https://github.com/kikito/anim8/blob/master/README.md

This command executes the test suite for the anim8 project. Purpose: Verify library functionality via busted framework. Dependencies: busted installed globally or locally. Inputs: Run from project root. Outputs: Test results in console. Limitations: Requires prior busted setup; no additional arguments shown.

```sh
busted
```

--------------------------------

### Create and Configure Animation in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

Example of creating a new animation with specified frames, durations, and an optional loop behavior. The durations can be uniform or defined per frame/range.

```lua
local animation = anim8.newAnimation(frames, durations, onLoop)
```

--------------------------------

### Create Grid and Get Frames in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

Demonstrates creating an animation grid and retrieving frames using anim8. The grid aligns with sprite sheet frames, and frame ranges are retrieved using intuitive syntax.

```lua
local gs = anim8.newGrid(32,98, 1024,768,  366,102,   1)
local frames = gs('1-7',1)
```

--------------------------------

### Requiring anim8 Library in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

This demonstrates the simple installation and import of the anim8 library. Purpose: Load anim8 for use in LÖVE projects. Dependencies: anim8.lua file in project path; review included license. Inputs: None. Outputs: anim8 module table. Limitations: Manual file copying required; no package manager integration.

```lua
local anim8 = require 'anim8'
```

--------------------------------

### Control Animation Playback in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

Methods to control animation playback, including moving to specific frames, pausing, resuming, and pausing at start or end positions.

```lua
animation:gotoFrame(frame)
animation:pause()
animation:resume()
animation:pauseAtEnd()
animation:pauseAtStart()
```

--------------------------------

### Get Animation Dimensions and Frame Info in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

Retrieves the size of the current frame and detailed drawing parameters adjusted for flipping and transformations. Useful for calculations involving animation frames.

```lua
animation:getDimensions()
animation:getFrameInfo(x,y, r, sx, sy, ox, oy, kx, ky)
```

--------------------------------

### Get animation frame rendering parameters in Lua

Source: https://context7.com/kikito/anim8/llms.txt

Retrieves frame information and transformed rendering parameters including position, rotation, scale, offset, and shear. Essential for advanced rendering techniques like sprite batches and manual drawing with transformations. Accounts for flip states and returns multiple values for direct use with love.graphics.draw.

```lua
local spriteSheet = love.graphics.newImage('sprites.png')
local grid = anim8.newGrid(32, 32, spriteSheet:getWidth(), spriteSheet:getHeight())
local animation = anim8.newAnimation(grid('1-8', 1), 0.1)

-- SpriteBatch usage for efficient rendering of many animated sprites
local spriteBatch = love.graphics.newSpriteBatch(spriteSheet, 1000)
local spriteIDs = {}

function initializeEntities()
  for i = 1, 100 do
    local x, y = math.random(0, 800), math.random(0, 600)
    local id = spriteBatch:add(animation:getFrameInfo(x, y, 0, 1, 1, 0, 0))
    table.insert(spriteIDs, {id=id, x=x, y=y, anim=animation:clone()})
  end
end

function love.update(dt)
  for _, sprite in ipairs(spriteIDs) do
    sprite.anim:update(dt)
    -- Update sprite batch with new frame
    spriteBatch:set(sprite.id, sprite.anim:getFrameInfo(sprite.x, sprite.y))
  end
end

function love.draw()
  love.graphics.draw(spriteBatch) -- Draw all 100 animated sprites in one call
end

-- Manual rendering with getFrameInfo
function customDraw(animation, image, x, y, rotation, scale)
  local frame, drawX, drawY, r, sx, sy, ox, oy, kx, ky =
    animation:getFrameInfo(x, y, rotation, scale, scale, 0, 0)
  love.graphics.draw(image, frame, drawX, drawY, r, sx, sy, ox, oy, kx, ky)
end
```

--------------------------------

### Get animation frame dimensions in Lua

Source: https://context7.com/kikito/anim8/llms.txt

Retrieves the width and height of the current animation frame for positioning and collision detection. Useful for centering animations on screen, drawing bounding boxes, and implementing collision systems. Returns two values: width and height in pixels.

```lua
local animation = anim8.newAnimation(grid('1-8', 1), 0.1)

function love.draw()
  local width, height = animation:getDimensions()

  -- Center animation on screen
  local screenWidth = love.graphics.getWidth()
  local screenHeight = love.graphics.getHeight()
  local x = (screenWidth - width) / 2
  local y = (screenHeight - height) / 2
  animation:draw(spriteSheet, x, y)

  -- Draw bounding box around animation
  love.graphics.rectangle('line', x, y, width, height)
end

-- Collision detection using animation dimensions
function checkCollision(anim1, x1, y1, anim2, x2, y2)
  local w1, h1 = anim1:getDimensions()
  local w2, h2 = anim2:getDimensions()

  return x1 < x2 + w2 and
         x2 < x1 + w1 and
         y1 < y2 + h2 and
         y2 < y1 + h1
end

-- Dynamic UI sizing
function drawHealthBar(animation, x, y)
  local width, height = animation:getDimensions()
  love.graphics.rectangle('fill', x, y - 10, width * healthPercentage, 5)
  animation:draw(spriteSheet, x, y)
end
```

--------------------------------

### Initialize Grid in Lua with anim8

Source: https://github.com/kikito/anim8/blob/master/README.md

Shows how to create a new grid object for extracting frames from an image. Depends on anim8 library. Takes frame dimensions, image size, and optional offset/border parameters. Returns a grid object. Only works with LÖVE images.

```lua
anim8.newGrid(frameWidth, frameHeight, imageWidth, imageHeight, left, top, border)
```

--------------------------------

### Create controllable animation (Lua)

Source: https://context7.com/kikito/anim8/llms.txt

Constructs an animation object from a sequence of frames with specified timing. Supports uniform durations, per-frame timing, and loop callbacks. Integrates with LÖVE's graphics system.

```Lua
local anim8 = require 'anim8'
local grid = anim8.newGrid(32, 32, 256, 128)

-- Basic animation: all frames display for 0.1 seconds
local walkAnimation = anim8.newAnimation(grid('1-8', 1), 0.1)

-- Per-frame duration using table with ranges
local attackAnimation = anim8.newAnimation(
  grid('1-5', 2),
  {['1-3']=0.1, ['4']=0.2, ['5']=0.3} -- Frames 1-3: 0.1s, frame 4: 0.2s, frame 5: 0.3s
)

-- Individual frame durations
local customAnimation = anim8.newAnimation(
  grid('1-4', 1),
  {0.05, 0.1, 0.15, 0.2} -- Each frame has specific duration
)

-- Animation with loop callback (pause after one loop)
local introAnimation = anim8.newAnimation(
  grid('1-10', 1),
  0.08,
  'pauseAtEnd' -- Built-in callback: plays once then stops on last frame
)

-- Custom loop callback function
local loopCount = 0
local countingAnimation = anim8.newAnimation(
  grid('1-6', 1),
  0.1,
  function(anim, loops)
    loopCount = loopCount + loops
    print("Animation has looped " .. loopCount .. " times")
  end
)
```

--------------------------------

### Create and Display Animation in Lua with anim8

Source: https://github.com/kikito/anim8/blob/master/README.md

This snippet demonstrates loading an image, creating a grid and animation using anim8, and updating/drawing the animation in a LÖVE game loop. It requires the anim8 library and LÖVE for graphics functions. Inputs include an image path and grid parameters; outputs are rendered animations. Limitations: Assumes sprite sheets with uniform frame sizes.

```lua
local anim8 = require 'anim8'

local image, animation

function love.load()
  image = love.graphics.newImage('path/to/image.png')
  local g = anim8.newGrid(32, 32, image:getWidth(), image:getHeight())
  animation = anim8.newAnimation(g('1-8',1), 0.1)
end

function love.update(dt)
  animation:update(dt)
end

function love.draw()
  animation:draw(image, 100, 200)
end
```

--------------------------------

### Animation Draw - Render animation frames with anim8 in LÖVE

Source: https://context7.com/kikito/anim8/llms.txt

Renders the current animation frame using LÖVE's graphics system. Accepts all standard love.graphics.draw parameters including position, rotation, scale, offset, and shearing. Automatically adjusts rendering parameters when animations are flipped. Shows basic drawing, transformations, and rendering multiple animated entities.

```lua
local spriteSheet = love.graphics.newImage('character.png')
local grid = anim8.newGrid(32, 32, spriteSheet:getWidth(), spriteSheet:getHeight())
local animation = anim8.newAnimation(grid('1-8', 1), 0.1)

function love.draw()
  -- Basic drawing at position (100, 200)
  animation:draw(spriteSheet, 100, 200)

  -- With rotation (45 degrees = 0.785 radians)
  animation:draw(spriteSheet, 200, 200, math.pi / 4)

  -- With scale (2x horizontal, 1.5x vertical)
  animation:draw(spriteSheet, 300, 200, 0, 2, 1.5)

  -- With origin offset (rotate around center of frame)
  local frameWidth, frameHeight = animation:getDimensions()
  animation:draw(spriteSheet, 400, 200, 0, 1, 1, frameWidth/2, frameHeight/2)

  -- Complete parameter set: image, x, y, rotation, scaleX, scaleY, offsetX, offsetY, shearX, shearY
  animation:draw(spriteSheet, 500, 200, 0, 1, 1, 0, 0, 0.2, 0)
end

-- Drawing multiple animated entities
local entities = {
  {x=100, y=100, anim=anim8.newAnimation(grid('1-4',1), 0.1)},
  {x=200, y=150, anim=anim8.newAnimation(grid('1-4',1), 0.1):flipH()},
  {x=300, y=200, anim=anim8.newAnimation(grid('1-4',1), 0.1)}
}

function love.draw()
  for _, entity in ipairs(entities) do
    entity.anim:draw(spriteSheet, entity.x, entity.y)
  end
end
```

--------------------------------

### Define Frame Sequence with Backwards Animation

Source: https://github.com/kikito/anim8/blob/master/README.md

Shows how to define a frame sequence including backwards frames to create looping animations that feel natural, such as a submarine submerging and resurfacing.

```lua
local frames = gs('1-7',1, '6-2',1)
```

--------------------------------

### Animation Update - Advance animation timing in LÖVE with anim8

Source: https://context7.com/kikito/anim8/llms.txt

Updates the animation's internal timer and advances frames based on elapsed time. Must be called regularly in love.update for animations to progress. Handles automatic looping and invokes loop callbacks. Demonstrates basic animation update and switching between different animations based on game state.

```lua
local animation = anim8.newAnimation(grid('1-8', 1), 0.1)

function love.update(dt)
  -- dt is delta time in seconds (e.g., 0.016 for 60 FPS)
  animation:update(dt)

  -- Animation automatically:
  -- - Accumulates time
  -- - Changes frames when duration threshold reached
  -- - Loops back to frame 1 after last frame
  -- - Calls onLoop callback when cycling
end

-- Example with multiple animations
local walkAnim = anim8.newAnimation(grid('1-6', 1), 0.08)
local idleAnim = anim8.newAnimation(grid('1-4', 2), 0.15)
local currentAnim = walkAnim

function love.update(dt)
  currentAnim:update(dt)

  -- Switch animations based on game state
  if player.velocity == 0 then
    if currentAnim ~= idleAnim then
      currentAnim = idleAnim
      currentAnim:gotoFrame(1) -- Reset to first frame
    end
  else
    currentAnim = walkAnim
  end
end
```

--------------------------------

### Create frame grid from sprite sheet (Lua)

Source: https://context7.com/kikito/anim8/llms.txt

Creates a grid object that divides a sprite sheet into individual frames based on specified dimensions. Handles spacing, borders, and offsets. Returns a grid factory for generating LÖVE Quads.

```Lua
local anim8 = require 'anim8'

-- Load a sprite sheet with 32x32 pixel frames
local spriteSheet = love.graphics.newImage('characters.png')
local imageWidth = spriteSheet:getWidth()   -- e.g., 256
local imageHeight = spriteSheet:getHeight() -- e.g., 128

-- Create a basic grid (no borders or offsets)
local grid = anim8.newGrid(32, 32, imageWidth, imageHeight)

-- Create a grid with 1-pixel border between frames
local gridWithBorder = anim8.newGrid(32, 32, imageWidth, imageHeight, 0, 0, 1)

-- Create a grid with offset origin (frames start at x=10, y=20)
local gridWithOffset = anim8.newGrid(32, 32, imageWidth, imageHeight, 10, 20, 0)

-- Grid automatically calculates frame capacity
-- For 256x128 image with 32x32 frames: width=8 columns, height=4 rows
print(grid.width, grid.height) -- Output: 8  4
```

--------------------------------

### Animation Control - Pause, resume, and frame navigation in anim8

Source: https://context7.com/kikito/anim8/llms.txt

Controls animation playback through pause/resume operations and enables direct frame navigation. Pausing prevents update() calls from advancing frames, while resuming continues normal playback. Frame navigation allows jumping to specific frames, useful for game state transitions, synchronization, and random frame selection.

```lua
local animation = anim8.newAnimation(grid('1-8', 1), 0.1)
local isPaused = false

function love.update(dt)
  animation:update(dt) -- Has no effect when paused
end

function love.keypressed(key)
  if key == 'space' then
    if isPaused then
      animation:resume()
      isPaused = false
      print("Animation resumed")
    else
      animation:pause()
      isPaused = true
      print("Animation paused at frame " .. animation.position)
    end
  end

  -- Pause on specific game events
  if key == 'p' then
    animation:pause()
    -- Animation freezes on current frame
    -- Useful for pause menus, cutscenes, etc.
  end

  if key == 'r' then
    animation:resume()
    -- Animation continues from where it stopped
  end
end
```

```lua
local animation = anim8.newAnimation(grid('1-10', 1), 0.1)

function love.keypressed(key)
  -- Jump to specific frames with number keys
  if key == '1' then
    animation:gotoFrame(1)
  elseif key == '5' then
    animation:gotoFrame(5)
  elseif key == '0' then
    animation:gotoFrame(10)
  end
end

-- Skip to climax of attack animation
function playAttackAnimation()
  attackAnim:gotoFrame(1)
  attackAnim:resume()
end

-- Synchronize multiple animations
function synchronizeAnimations(targetFrame)
  characterAnim:gotoFrame(targetFrame)
  weaponAnim:gotoFrame(targetFrame)
  effectAnim:gotoFrame(targetFrame)
end

-- Random frame for variety
function startAtRandomFrame(anim, frameCount)
  local randomFrame = math.random(1, frameCount)
  anim:gotoFrame(randomFrame)
end
```

--------------------------------

### Animation: flipH and flipV in Lua

Source: https://context7.com/kikito/anim8/llms.txt

flipH and flipV methods mirror the animation horizontally or vertically by inverting scale and offsets during rendering, modifying the instance in-place for chaining. They toggle flip states based on input like direction keys in game loops. Dependent on anim8 library; no direct inputs beyond the method call, outputs self for chaining, with limitations on non-uniform scaling.

```lua
local animation = anim8.newAnimation(grid('1-8', 1), 0.1)

-- Flip horizontally (mirror left-right)
animation:flipH()

-- Flip vertically (mirror top-bottom)
animation:flipV()

-- Toggle flip states
function love.keypressed(key)
  if key == 'h' then
    animation:flipH() -- Flip once
    animation:flipH() -- Flip again (returns to original)
  end
end

-- Direction-based character movement
local walkAnimation = anim8.newAnimation(grid('1-6', 1), 0.08)
local facingRight = true

function love.update(dt)
  walkAnimation:update(dt)

  if love.keyboard.isDown('left') then
    if facingRight then
      walkAnimation:flipH()
      facingRight = false
    end
    playerX = playerX - 100 * dt
  elseif love.keyboard.isDown('right') then
    if not facingRight then
      walkAnimation:flipH()
      facingRight = true
    end
    playerX = playerX + 100 * dt
  end
end

-- Create pre-flipped variants using chaining
local baseAnim = anim8.newAnimation(grid('1-4', 1), 0.1)
local rightAnim = baseAnim:clone()
local leftAnim = baseAnim:clone():flipH()
local upsideDownAnim = baseAnim:clone():flipV()
local invertedAnim = baseAnim:clone():flipH():flipV()
```

--------------------------------

### Animation: pauseAtEnd and pauseAtStart in Lua

Source: https://context7.com/kikito/anim8/llms.txt

The pauseAtEnd method positions the animation at its last frame and pauses playback, ideal for one-time effects like death sequences. pauseAtStart resets to the first frame and pauses, useful for restarting states. These methods integrate with anim8.newAnimation and callbacks like onLoop, requiring the anim8 library and a grid function; they have no inputs beyond the animation instance and output a paused state without altering frame data.

```lua
local deathAnimation = anim8.newAnimation(grid('1-8', 3), 0.1)
local spawnAnimation = anim8.newAnimation(grid('1-6', 4), 0.08)

function characterDies()
  currentAnimation = deathAnimation
  deathAnimation:gotoFrame(1)
  -- Play death animation once, then freeze on last frame
  deathAnimation.onLoop = function(anim)
    anim:pauseAtEnd()
  end
end

-- Alternative: use built-in pauseAtEnd callback
local oneTimeAnimation = anim8.newAnimation(grid('1-10', 1), 0.1, 'pauseAtEnd')

-- Reset animation to beginning and stop
function resetCharacterAnimation()
  currentAnimation:pauseAtStart()
  -- Animation now at frame 1 and paused
  -- Useful for resetting state
end

-- Cinematic sequence control
function playCutscene()
  cutsceneAnim:gotoFrame(1)
  cutsceneAnim:resume()
  -- After animation plays once, freeze on last frame for dramatic effect
  cutsceneAnim.onLoop = function(anim)
    anim:pauseAtEnd()
    startNextCutscenePhase()
  end
end
```

--------------------------------

### Animation: clone in Lua

Source: https://context7.com/kikito/anim8/llms.txt

The clone method creates an independent copy of the animation with identical properties, resetting timing to frame 1 and timer 0 while preserving flip states. It enables multiple instances for characters or enemies, allowing independent updates with different speeds. Requires the anim8 library; outputs a new animation object that can be modified via chaining like flipH without affecting the original.

```lua
local baseWalkAnimation = anim8.newAnimation(grid('1-6', 1), 0.1)

-- Create multiple independent instances for different characters
local player1Anim = baseWalkAnimation:clone()
local player2Anim = baseWalkAnimation:clone()
local player3Anim = baseWalkAnimation:clone()

function love.update(dt)
  -- Each animation updates independently
  player1Anim:update(dt)
  player2Anim:update(dt * 1.5) -- Walks faster
  player3Anim:update(dt * 0.5) -- Walks slower
end

-- Create flipped variations
local walkRight = anim8.newAnimation(grid('1-8', 1), 0.08)
local walkLeft = walkRight:clone():flipH() -- Clone and flip horizontally

-- Efficient enemy spawning
local enemyAnimationTemplate = anim8.newAnimation(grid('1-4', 2), 0.12)
local enemies = {}

function spawnEnemy(x, y)
  table.insert(enemies, {
    x = x,
    y = y,
    animation = enemyAnimationTemplate:clone() -- Each enemy has independent animation
  })
end

-- Chain cloning with modifications
local baseAnim = anim8.newAnimation(grid('1-6', 1), 0.1)
local flippedAnim = baseAnim:clone():flipH()
local mirroredAnim = baseAnim:clone():flipH():flipV()
```

--------------------------------

### Adding and Updating Frames in SpriteBatch using anim8 in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

This snippet shows how to add a quad to a Love2D SpriteBatch using anim8's getFrameInfo for frame retrieval, and later update it. Purpose: Efficiently render animated frames in batches. Dependencies: anim8 library and Love2D SpriteBatch. Inputs: frame positions (x,y), rotation (r), scales (sx,sy), offsets (ox,oy), shears (kx,ky based on flip). Outputs: Instance ID and quad for batch rendering. Limitations: Assumes pre-initialized animation object; manual ID management required.

```lua
local id = spriteBatch:add(animation:getFrameInfo(x,y,r,sx,sy,ox,oy,kx,ky))

...

spriteBatch:set(id, animation:getFrameInfo(x,y,r,sx,sy,ox,oy,kx,ky))
```

--------------------------------

### Clone and Flip Animations in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

Cloning creates a copy of the animation reset to the first frame. Flipping applies horizontal or vertical mirroring during drawing without creating new animations.

```lua
animation:clone()
animation:flipH()
animation:flipV()
```

--------------------------------

### Draw Current Animation Frame in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

Draws the current animation frame with transformations such as position, angle, and scale. Parameters align with love.graphics.draw but handle flipping automatically.

```lua
animation:draw(image, x,y, angle, sx, sy, ox, oy, kx, ky)
```

--------------------------------

### Extract frames using coordinates or ranges (Lua)

Source: https://context7.com/kikito/anim8/llms.txt

Retrieves one or more frames from the grid using flexible coordinate notation. Supports individual frames, ranges, and reverse sequences. The grid object itself is callable as a shortcut to this method.

```Lua
local grid = anim8.newGrid(32, 32, 256, 128)

-- Get a single frame at column 1, row 1
local singleFrame = grid:getFrames(1, 1)

-- Get multiple specific frames
local frames = grid:getFrames(1,1, 2,1, 3,1) -- First three frames of row 1

-- Use string ranges for rows or columns
local row1Frames = grid:getFrames('1-8', 1)     -- All frames in row 1
local col2Frames = grid:getFrames(2, '1-4')     -- All frames in column 2

-- Combine ranges and specific coordinates
local mixedFrames = grid:getFrames('1-4',1, 1,2, '5-8',1) -- Row 1 frames 1-4, frame at (1,2), row 1 frames 5-8

-- Reverse ranges for backward sequences
local reverseFrames = grid:getFrames('8-2', 1)  -- Row 1 frames in reverse (8,7,6,5,4,3,2)

-- Use grid as a function (shortcut)
local quickFrames = grid('1-8', 1) -- Same as grid:getFrames('1-8', 1)

-- Create looping animation with forward-backward sequence
local walkFrames = grid('1-4', 1, '3-2', 1) -- Walk cycle: 1,2,3,4,3,2
```

--------------------------------

### Update Animation Frame in Lua

Source: https://github.com/kikito/anim8/blob/master/README.md

Used in the game loop to update the animation frame based on elapsed time. This should be called in love.update(dt) to maintain proper timing.

```lua
animation:update(dt)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.