Home

Welcome to the beat4sprite wiki.

Introduction

beat4sprite has its own actors and a Builder metaclass to create sets of synced animations based on scripts. The actors inherit the features of the game engine classes and tapLua's implementation. The main function of these actors is for their animation to be synced to the game current song beat.

Common use functions:

beat4sprite.Load( scriptName ) -- Tries to load a script from `beat4sprite/Scripts`
beat4sprite.filePath( animationName, optionalFile ) -- Returns a BGAnimations path in case you're referencing another animation.
beat4sprite.randomAnimation() -- Returns a random animation from the game BGAnimations folder.
beat4sprite.songBackgroundPath()

Builders

Builders create animations easily and simply based on scripts. A builder can contain sub builders inside it to stack animations one after another. On creation, builders have their own spawn setup.

-- A simple builder. By default the script is Tile.lua for tiling sprites together fitting screen.

local myBuilder = beat4sprite.Builder {

    Texture = "myFolder/myTexture.png", -- Located at beat4sprite/Resources/...

    ... -- Any attributes or properties I want the builder to have.

}

-- A set of builders in a builder...

local myBuilder = beat4sprite.Builder {

    { Texture = "myFolder/myTexture.png", ... }, -- Builder 1
    { Texture = "myFolder/myTexture2.png", ... }, -- Builder 2
    { Texture = "myFolder/myTexture3.png", ... } -- Builder 3

}

-- Some properties like Scale and Filter can be inherited by the nested builders.

Load() returns the animation.

return beat4sprite.Builder.Load { -- Returns the animation and actors directly.

    Texture = "myFolder/myTexture.png",

    ... -- Any attributes or properties I want the builder to have.

}

--- Another example...

local builder = beat4sprite.Builder { ... }            ... -- Does changes to the builder.

return builder:Load()

Builders can be merged using merge().

local A = beat4sprite.Builder { ... }            local B = beat4sprite.Builder { ... }

A:merge(B) -- Returns a new builder based on the merge of builder B onto builder A.

Builders have default values, but they can be changed by writing a function to create custom Builders. Like the Retro builder function in Builder.lua:

local function Retro(input)

    local scale = SCREEN_HEIGHT / 240           input.Scale = scale           input.Filter = false             return Builder(input)

end

A builder can have a layers table for convenience:

local Actor1 = Def.Actor {}        local Actor2 = Def.ActorFrame {...}

local myBuilder = beat4sprite.Builder {

    Layers = { Back = { Actor1 }, Front = { Actor2 } }

}

Commands

Builders commands are arrays that contain the names of the commands that will be played in the scripts. They have a couple of operations.

Paths

Textures are located in beat4sprite/Resources/ and scripts in beat4sprite/Scripts/. If the path starts with / it's considered an absolute path and if it starts with "./" it will be considered a relative path to where the script was executed from.

Actors

• The actors can be found in Actor.lua and their additional functions can be found in Functions.lua.

• Sprites additional functions can be found in Sprite.lua.

• Functions related to frame to frame updates are at Update.lua.

Commands

Commands.lua contains functions for animations that are cyclic (queue themselves forever) and they work as commands for the actor table.

local Commands = beat4sprite.Actor.Commands             local SpinX = Commands.SpinX

beat4sprite.Sprite { SpinCommand = SpinX } -- Sprite that will eventually spin forever.

Theme modules

beat4sprite can load theme modules in beat4sprite/Modules/ for specific theme gameplay animations.

For example, beat4sprite OutFox soundwaves animations have their own module that has functions related to the theme. These functions are used in the animations to achieve a similar look to the theme.

Engine aspects

There are some common issues that can happen when creating global BGAnimations for gameplay. This is what I have gathered:

• beat4sprite scripts using actor frame textures like Tile.lua won't work properly in older legacy builds due to the limitation of OpenGL with non power of two sized textures.

• Consider that OnCommand and GainFocusCommand will execute each time the animation is replayed. The engine internally resets the state of all the animation on replay.

• To ensure your animations work properly on replay have two animations only in your BGAnimations folder, one containing the original animation and the other one using loadfile() to load the former and then proceed to test the behavior on gameplay.

• Adding children dynamically can cause crashes if not handled properly.

• If the main returned actor uses OnCommand some functions won't work. GainFocusCommand will work.

  -- Sets the size and centers the quad but diffusing doesn't work.
  return Def.Quad { OnCommand=function(self) self:setsize(128,128):Center():diffuse( Color.Red ) end }