ParalX.lua

From PGE Wiki
Jump to: navigation, search


*This library is included in Beta 3.*

ParalX is a LunaLua library designed to create parallax background layers in Super Mario Bros X.

(If paralX2.lua released, this one will be deprecated.)

Installation

The latest version of this API is only included in SMBX2; No external download available as of yet.

(LunaLua also include an old version for this API but not recommend for use)

How to use

To load the ParalX library for a specific level, add this line to the top of lunadll.lua:

local paralX = API.load("paralX")

This will load the ParalX API. From there, you can use paralX.create {table properties} to make Parallax layer objects.

Example

The following code was taken from this example level:

local paralX = API.load("paralX")


-- Load the images
local fg0Img = Graphics.loadImage("fg0.png")
local fg1Img = Graphics.loadImage("fg1.png")

local bg0Img = Graphics.loadImage("bg0.png")
local bg1Img = Graphics.loadImage("bg1_alpha.png")
local pyramidBgImg = Graphics.loadImage("bg2.png")
local cloudBgImg = Graphics.loadImage("bg3_trans.png")
local skyBgImg = Graphics.loadImage("bg4.png")

-- Declare a variable for the pyramid so we can access it in onTick
local pyramidBg

-- Create the layers
function onStart()
	paralX.create{image=fg0Img, y=-360, priority=-1, repeatY=false, parallaxX=1.45, parallaxY=1.25}
	paralX.create{image=fg1Img, x=-80, y=-780, priority=-0.5, repeatX=false, repeatY=false, parallaxX=2, parallaxY=1.5, alpha=0.5}
	
	paralX.create{image=bg0Img, y=-80, priority=-96, repeatY=false, parallaxX=0.6, parallaxY=0.6}
	paralX.create{image=bg1Img, x= 80, y=-60, priority=-96.2, repeatY=false, parallaxX=0.45, parallaxY=0.35, alpha=0.8}

	pyramidBg = paralX.create{image=pyramidBgImg, x=1464, y=-120, priority=-96.1, repeatX=false, repeatY=false, parallaxX=0.55, parallaxY=0.5}
	paralX.create{image=cloudBgImg, y=-80, priority=-96.3, repeatY=false, parallaxX=0.125, parallaxY=0.125, speedX=0.0625}
	paralX.create{image=skyBgImg, y= 00, priority=-96.4, repeatX=false, repeatY=false, parallaxX=0, parallaxY=0}
end

function onTick()
	pyramidBg.y = -120 + 32*math.sin(lunatime.time())
end

Documentation

Functions

ParalX coroutine functions
Type Function/Field Return values/Value type Description
function paralX.create (table properties) nil Creates a new parallax layer with its' properties defined via named arguments.
variable paralX.debug boolean If true, will display debug information for each parallax layer. If textblox is detected, the debug information will be displayed via small, condensed text.
variable paralX.useOldPositioning boolean If true, will parallax layers will be displayed using the pre-1.4 positioning math.

Properties

The following properties can be both defined in paralX.create (args) and accessed via parallaxObj.propertyName:

Name Type Is Optional? Default Value Description
image LuaImageResource no nil The image used; animations can be used as vertical sheets, though the frames property will need to be set accordingly (see below).
frames number yes 1 The number of frames in the animation.
animSpeed number yes 0.05 The rate at which the layer cycles through its' frames of animation.
alpha number yes 1 The transparency of the layer; 0 = invisible, 1 = completely opaque
sections number or table of number yes {1, 2... 21} The section(s) in which the parallax layer is shown.
priority number yes -96 The depth at which the layer is shown; see this list for the sorting order.
x number yes 0 The horizontal offset of the layer.
y number yes 0 The vertical offset of the layer.
alignX constant yes paralX.ALIGN_LEFT The side of the screen the layer aligns to; can be paralX.ALIGN_LEFT, paralX.ALIGN_MID or paralX.ALIGN_RIGHT. (v1.4.4+)
alignY constant yes paralX.ALIGN_TOP The side of the screen the layer aligns to; can be paralX.ALIGN_TOP, paralX.ALIGN_MID or paralX.ALIGN_BOTTOM. (v1.4.4+)
parallaxX number yes 0.75 The rate at which the layer pans horizontally with the camera; 0 = fixed position on the screen, 1 = pans with the level, >1 = pans more than the level, <0 = pans in reverse.
parallaxY number yes 0.75 The rate at which the layer pans vertically with the camera; 0 = fixed position on the screen, 1 = pans with the level, >1 = pans more than the level, <0 = pans in reverse.
speedX number yes 0 The horizontal speed of the layer independent of panning.
speedY number yes 0 The vertical speed of the layer independent of panning.
repeatX boolean yes true if true, the image is tiled horizontally.
repeatY boolean yes true if true, the image is tiled vertically.
gapX number yes 0 The horizontal separation between tiles.
gapY number yes 0 The vertical separation between tiles.