Skip to content

Home

Jump to bottom
alexanderdna edited this page Oct 30, 2018 · 6 revisions

amour - a basic scene graph library for LÖVE.

Overview

Installation

Just copy amour into the root folder of your game.

Dependencies

  • classic for OOP functionalities
  • flux (optional) for tweening functionalities

Limitations

  • No support for z-index: child nodes added later will be drawn later.
  • Although transform properties like x, y, r, etc. can be read directly, they must be set via updateXXX() functions or the transforms won't be updated.
  • Usage of flux on transform properties must be done via node:flux() instead of flux.to(node, ...) to make sure node transform is updated.

Get Started

local Scene = require 'amour.scene'
local Rect = require 'amour.rect'
local Text = require 'amour.text'

local scene

function love.load()
    scene = Scene(480, 320)

    local bg = Rect(scene.w * 0.5, scene.h * 0.5, scene.w, scene.h, { 0.2, 0.2, 0.2, 1 })
    scene:addChild(bg)

    local title = Text(scene.w * 0.5, 10, 14, "Je t'aime!", { 1, 0, 0, 1})
    title:updateAnchor(0.5, 0)
    scene:addChild(title)
end

function love.draw()
    scene:draw()
end

API

Node

Fields

x, y

Position of the node.

w, h

Size of the node.

r

Rotation of the node (in radians).

sx, sy

Scale of the node.

ax, ay

Anchor point of the node. Default value is (0.5, 0.5).

visible

If set to false, the node and its children will not be rendered.

Functions

Node(x, y, w, h)

Creates and returns a node object.

  • x: x coordinate
  • y: y coordinate
  • w: width
  • h: height

addChild(node [, index])

Adds a child node to this node.

  • node: child node to add
  • index: used when child node is to be inserted at a specific place in the child list

removeChild(node)

Removes a child node from this node.

  • node: child node to remove

reorderChild(node, index)

Moves a child node to a new place in the child list.

  • node: child node to move
  • index: new index of the child node

getLeftTop()

Returns the left X and top Y of the node. Useful in render function.

draw()

Draws the node.

realdraw()

To be overriden in derived class to perform actual rendering.

updatePosition(x, y)

Sets new values for x and y, and updates the node transform.

updateRotation(r)

Sets new value for r, and updates the node transform.

updateSize(w, h)

Sets new values for w and h, and updates the node transform.

updateScale(sx, sy)

Sets new values for sx and sy, and updates the node transform.

updateAnchor(ax, ay)

Sets new values for ax and ay, and updates the node transform.

updateTransform([needPropagation])

(USED INTERNALLY) Updates the node transform according to current transform values.

  • needPropagation: if true, calls this function on all children.

containsPoint(gx, gy)

Returns true if this node contains the point at global coordinates (gx, gy).

flux(duration, changes [, group])

Performs a tween using flux library and returns the tween object.

  • duration: how long the tween lasts, in seconds
  • changes: a table of changes to the node's fields
  • group: optional flux tween group

Any tweens on transform values of a node should be done via this function instead of flux.to in order to update the transform accordingly.

Scene

Scene(designWidth, designHeight, sizeMode)

Creates a scene that adapts to current dimensions of the game. The scene node may be scaled to match the game window.

  • designWidth: design width
  • designHeight: design height
  • sizeMode (default 'expand'): how the scene adapts to window size
    • 'expand': scaled to smaller dimension, the other will be expanded to fill
    • 'cut': scaled to greater dimension, the other will be cut to fit
    • 'width': prioritize width, height will be expanded or cut accordingly
    • 'height': prioritize height, width will be expanded or cut accordingly

PixelScene

PixelScene(designWidth, designHeight)

Creates a pixel-perfect scene. Design size will be multiplied with an integral value big enough that the result is less than or equal to the screen size. The scene will then be expanded to fill the whole screen.

  • designWidth: minimum design width
  • designHeight: minimum design height

Rect

color

Current color of the rectangle, in the form { r, g, b, a }.

Rect(x, y, w, h [, color, mode, lineWidth])

Creates and returns a rectangular node.

  • x: x coordinate
  • y: y coordinate
  • w: width
  • h: height
  • color (default {1,1,1,1}): color of the rectangle
  • mode (default 'fill'): draw mode, 'fill' or 'line'
  • lineWidth (default 1): line width if mode is line

Text

color

Current color of the text, in the form { r, g, b, a }.

Text(x, y, font, textString [, color])

Creates and returns a text node.

  • x: x coordinate
  • y: y coordinate
  • font: a font object, or just font size
  • textString: initial text string
  • color (default {1,1,1,1}): text color

getString()

Returns current text string.

setString(textString [, wrapLimit, alignMode])

Sets new text string.

  • textString: new text string, or a coloredtext table as defined by LÖVE
  • wrapLimit: maximum width before line-break happens
  • alignMode: text alignment, 'left', 'center' or 'right'

Image

color

Current color of the image, in the form { r, g, b, a }.

Image(x, y, image [, color])

Creates and returns an image node.

  • x: x coordinate
  • y: y coordinate
  • image: an Image object or path to the image file
  • color (default {1,1,1,1}): text color

Quad

color

Current color of the quad, in the form { r, g, b, a }.

Quad(x, y, qx, qy, qw, qh, image [, color])

Creates and returns a quad node.

  • x: x coordinate
  • y: y coordinate
  • qx: x coordinate of the quad in the image
  • qy: y coordinate of the quad in the image
  • qw: width of the quad
  • qh: height of the quad
  • image: an Image object or path to the image file
  • color (default {1,1,1,1}): text color

Wrapper

Wrapper is a generic node that supports rendering of custom drawable types.

Wrapper(x, y, w, h, target, renderer)

Creates and returns a wrapper node.

  • x: x coordinate
  • y: y coordinate
  • w: width
  • h: height
  • target: drawable object to render
  • renderer: custom render function with the signature function(target, x0, y0)

Example of using Wrapper to draw a gradient mesh:

function love.load()
    local mesh = love.graphics.newMesh(
        {
            { 0,0, 0,0, 1,1,1,1 },
            { 100,0, 1,0, 1,1,1,1 },
            { 100,100, 1,1, 1,0,0,1 },
            { 0,100, 0,1, 1,0,0,1 },
        }, 'fan')

    wrapper = Wrapper(120, 120, 100, 100, mesh,
        function(target, x0, y0)
            love.graphics.draw(target, x0, y0)
        end)
end

-- ...

function love.draw()
    wrapper:draw()
end

Clone this wiki locally