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 nested builders inside it to stack animations one after another. On creation, builders have their own 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

}

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(). This function merges the initial inputs of the builder.

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

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

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 }

}

A custom inherited builder implementation can be done. Retro.lua is an example.

Commands

Builders commands are arrays that contain the names of the commands that will be played in the scripts. The indexes control the order of execution of the commands.

Paths

Textures are located in beat4sprite/Resources/ and scripts in beat4sprite/Scripts/. Absolute and relative paths work as usual but consider using tapLua.resolvePath() to solve relative paths when returning a tail call since this is a current limitation.

Actors

• Actors can be found in Actor.lua and their functions can be found in Functions.lua.

• Sprites 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 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 that animations scripts work properly on replay. Try having 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 }

• This is based on the game engine behaviour in Background.cpp