love.scene

Minimal scene graph designed for Love2D
https://bitbucket.org/itraykov/love.scene

scene

This is the main module of the scene graph library.
scene.newLayer(x, y)Creates a new layer object. Alternatively, you can use layer:newLayer or view:newLayer.
scene.newSprite(x, y)Creates a new sprite object. Alternatively, you can use layer:newSprite or view:newSprite.
scene.newView(x, y, width, height)Creates a new view object. If no parameters are supplied, the view takes on the dimensions of the window.

scene.newLayer(x, y)

Creates a new layer object. Alternatively, you can use layer:newLayer or view:newLayer.
numberx
X coordinate
numbery
Y coordinate
Returns
layer New layer object

scene.newSprite(x, y)

Creates a new sprite object. Alternatively, you can use layer:newSprite or view:newSprite.
numberx
X coordinate
numbery
Y coordinate
Returns
sprite New sprite object

scene.newView(x, y, width, height)

Creates a new view object. If no parameters are supplied, the view takes on the dimensions of the window.
numberx (optional)
X-position in pixels
numbery (optional)
Y-position in pixels
numberwidth (optional)
Width in pixels
numberheight (optional)
Height in pixels
Returns
view New view object



node

Abstract scene graph node.
node.new(x, y, mt)This is an internal function.
node:compareDepth(other)Compares the depth of two nodes, based on their Y-coordinates.
node:destroy()Destroys the node removing it from its parent layer.
node:getDepth()Gets the depth index relative to other nodes in the parent layer.
node:getPosition()Gets the position of the node.
node:getRoot()Returns the root layer of the node.
node:getRotation()Gets the rotation of the node.
node:getScale()Gets the scale of the node.
node:getTransform()Gets the position and rotation of the node.
node:getVisible()Gets the visibility of the node. Non-visible nodes are not drawn at all.
node:localToParent(x, y)Converts a position from local to parent coordinates. The center of the parent layer is its origin.
node:localToScene(x, y)Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.
node:localToWindow(x, y)Converts a position from local to window coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
node:parentToLocal(x, y)Converts a position from parent to local coordinates. The center of the parent layer is its origin.
node:sceneToLocal(x, y)Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.
node:setDepth(index)Sets the depth index relative to other nodes in the parent layer. Setting the depth to 1 will draw the node first, before all others. Setting the depth to 0 will draw the node last, after all others. This depth index may shift as node are added, removed or sorted.
node:setParent(parent)Sets the parent layer of the node. All nodes have just a single parent.
node:setPosition(x, y)Sets the position of the node.
node:setRotation(angle)Sets the rotation of the node.
node:setScale(sx, sy)Sets the scale of the node.
node:setTransform(x, y, angle)Sets the position and rotation of the node.
node:setVisible(True)Sets the visibility of the node. Non-visible nodes are not drawn at all.
node:windowToLocal(x, y)Converts a position from window to local coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.

node.new(x, y, mt)

This is an internal function.
numberx
X-coordinate
numbery
Y-coordinate
tablemt (optional)
Metatable of base object
Returns
node New node

node:compareDepth(other)

Compares the depth of two nodes, based on their Y-coordinates.
nodeother
Other other
Returns
boolean True if this node is in front of the other

node:destroy()

Destroys the node removing it from its parent layer.

node:getDepth()

Gets the depth index relative to other nodes in the parent layer.
Returns
number Depth index

node:getPosition()

Gets the position of the node.
Returns
number X-coordinate
number Y-coordinate

node:getRoot()

Returns the root layer of the node.
Returns
layer Root layer

node:getRotation()

Gets the rotation of the node.
Returns
number Angle in radians

node:getScale()

Gets the scale of the node.
Returns
number X-axis scale
number Y-axis scale

node:getTransform()

Gets the position and rotation of the node.
Returns
number X-coordinate
number Y-coordinate
number Angle in radians

node:getVisible()

Gets the visibility of the node. Non-visible nodes are not drawn at all.
Returns
boolean True if visible

node:localToParent(x, y)

Converts a position from local to parent coordinates. The center of the parent layer is its origin.
numberx
Local X-coordinate
numbery
Local Y-coordinate
Returns
number Parent X-coordinate
number Parent Y-coordinate

node:localToScene(x, y)

Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.
numberx
Local X-coordinate
numbery
Local Y-coordinate
Returns
number Scene X-coordinate
number Scene Y-coordinate

node:localToWindow(x, y)

Converts a position from local to window coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
numberx
Local X-coordinate
numbery
Local Y-coordinate
Returns
number Window X-coordinate
number Window Y-coordinate

node:parentToLocal(x, y)

Converts a position from parent to local coordinates. The center of the parent layer is its origin.
numberx
Parent X-coordinate
numbery
Parent Y-coordinate
Returns
number Local X-coordinate
number Local Y-coordinate

node:sceneToLocal(x, y)

Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.
numberx
Scene X-coordinate
numbery
Scene Y-coordinate
Returns
number Local X-coordinate
number Local Y-coordinate

node:setDepth(index)

Sets the depth index relative to other nodes in the parent layer. Setting the depth to 1 will draw the node first, before all others. Setting the depth to 0 will draw the node last, after all others. This depth index may shift as node are added, removed or sorted.
numberindex
Depth index (could be negative)

node:setParent(parent)

Sets the parent layer of the node. All nodes have just a single parent.
layerparent
New parent layer

node:setPosition(x, y)

Sets the position of the node.
numberx
X-coordinate
numbery
Y-coordinate

node:setRotation(angle)

Sets the rotation of the node.
numberangle
Angle in radians

node:setScale(sx, sy)

Sets the scale of the node.
numbersx
X-axis scale
numbersy
Y-axis scale

node:setTransform(x, y, angle)

Sets the position and rotation of the node.
numberx
X-coordinate
numbery
Y-coordinate
numberangle
Angle in radians

node:setVisible(True)

Sets the visibility of the node. Non-visible nodes are not drawn at all.
booleanTrue
if visible

node:windowToLocal(x, y)

Converts a position from window to local coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
numberx
Window X-coordinate
numbery
Window Y-coordinate
Returns
number Local X-coordinate
number Local Y-coordinate



sprite

Sprites are nodes in the scene which can be translated, scaled or rotated. Each sprite is assigned a "drawable" graphic, usually an image, quad or text. Sprites can also be assigned a specific color, alpha value and blending mode.
node
node:compareDepth(other)Compares the depth of two nodes, based on their Y-coordinates.
node:getDepth()Gets the depth index relative to other nodes in the parent layer.
node:getPosition()Gets the position of the node.
node:getRoot()Returns the root layer of the node.
node:getRotation()Gets the rotation of the node.
node:getScale()Gets the scale of the node.
node:getTransform()Gets the position and rotation of the node.
node:getVisible()Gets the visibility of the node. Non-visible nodes are not drawn at all.
node:localToParent(x, y)Converts a position from local to parent coordinates. The center of the parent layer is its origin.
node:localToScene(x, y)Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.
node:localToWindow(x, y)Converts a position from local to window coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
node:parentToLocal(x, y)Converts a position from parent to local coordinates. The center of the parent layer is its origin.
node:sceneToLocal(x, y)Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.
node:setDepth(index)Sets the depth index relative to other nodes in the parent layer. Setting the depth to 1 will draw the node first, before all others. Setting the depth to 0 will draw the node last, after all others. This depth index may shift as node are added, removed or sorted.
node:setParent(parent)Sets the parent layer of the node. All nodes have just a single parent.
node:setPosition(x, y)Sets the position of the node.
node:setRotation(angle)Sets the rotation of the node.
node:setScale(sx, sy)Sets the scale of the node.
node:setTransform(x, y, angle)Sets the position and rotation of the node.
node:setVisible(True)Sets the visibility of the node. Non-visible nodes are not drawn at all.
node:windowToLocal(x, y)Converts a position from window to local coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
sprite
sprite.new(x, y, mt)This is an internal function. Please use scene.newSprite or layer.newSprite instead.
sprite:destroy()Destroys the sprite and removes it from its parent node.
sprite:draw()This is an internal function.
sprite:getAlpha()Gets the alpha value.
sprite:getColor()Gets the color.
sprite:getGraphic()Gets the "drawable" graphic and quad of the sprite.
sprite:getMode()Gets the blending mode.
sprite:getShader()Gets the shader used when drawing the sprite.
sprite:setAlpha(alpha)Sets the alpha value.
sprite:setColor(red, green, blue)Sets the color.
sprite:setGraphic(drawable, quad, x, y, angle, sx, sy, ox, oy, kx, ky)Sets a "drawable" graphic or a quad for the sprite. This could be an image, text, mesh, canvas, etc. The "drawable" graphic can be transformed relative to the sprite's origin.
sprite:setMode(mode)Sets the blending mode.
sprite:setShader(shader)Sets the shader used when drawing the sprite.

sprite.new(x, y, mt)

This is an internal function. Please use scene.newSprite or layer.newSprite instead.
numberx
X coordinate
numbery
Y coordinate
tablemt (optional)
Metatable of base object
Returns
sprite New sprite

sprite:destroy()

Destroys the sprite and removes it from its parent node.

sprite:draw()

This is an internal function.

sprite:getAlpha()

Gets the alpha value.
Returns
number Alpha value (0-1)

sprite:getColor()

Gets the color.
Returns
number Red value (0-1)
number Green value (0-1)
number Blue value (0-1)

sprite:getGraphic()

Gets the "drawable" graphic and quad of the sprite.
Returns
userdata Drawable graphic
userdata Quad or nil

sprite:getMode()

Gets the blending mode.
Returns
string mode Blend mode

sprite:getShader()

Gets the shader used when drawing the sprite.
Returns
userdata Shader object

sprite:setAlpha(alpha)

Sets the alpha value.
numberalpha
Alpha value (0-1)

sprite:setColor(red, green, blue)

Sets the color.
numberred
Red value (0-1)
numbergreen
Green value (0-1)
numberblue
Blue value (0-1)

sprite:setGraphic(drawable, quad, x, y, angle, sx, sy, ox, oy, kx, ky)

Sets a "drawable" graphic or a quad for the sprite. This could be an image, text, mesh, canvas, etc. The "drawable" graphic can be transformed relative to the sprite's origin.
userdatadrawable
Drawable graphic
userdataquad (optional)
Optional quad
numberx (0)
X coordinate
numbery (0)
y coordinate
numberangle (0)
Angle
numbersx (1)
X axis scale
numbersy (1)
Y axis scale
numberox (0)
X axis offset
numberoy (0)
Y axis offset
numberkx (0)
X axis shearing
numberky (0)
Y axis shearing

sprite:setMode(mode)

Sets the blending mode.
stringmode
Blend mode: "alpha", "add", "subtract" or "multiply"

sprite:setShader(shader)

Sets the shader used when drawing the sprite.
userdatashader
Shader object



layer

Layers are basically groups of nodes, containing either sprites or other nested layers. Layers are helpful in ordering nodes along the Z-axis. Layers are used to build things like parallax, huds, minimaps and so on.
node
node:compareDepth(other)Compares the depth of two nodes, based on their Y-coordinates.
node:getDepth()Gets the depth index relative to other nodes in the parent layer.
node:getPosition()Gets the position of the node.
node:getRoot()Returns the root layer of the node.
node:getRotation()Gets the rotation of the node.
node:getScale()Gets the scale of the node.
node:getTransform()Gets the position and rotation of the node.
node:getVisible()Gets the visibility of the node. Non-visible nodes are not drawn at all.
node:localToParent(x, y)Converts a position from local to parent coordinates. The center of the parent layer is its origin.
node:localToScene(x, y)Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.
node:localToWindow(x, y)Converts a position from local to window coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
node:parentToLocal(x, y)Converts a position from parent to local coordinates. The center of the parent layer is its origin.
node:sceneToLocal(x, y)Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.
node:setDepth(index)Sets the depth index relative to other nodes in the parent layer. Setting the depth to 1 will draw the node first, before all others. Setting the depth to 0 will draw the node last, after all others. This depth index may shift as node are added, removed or sorted.
node:setParent(parent)Sets the parent layer of the node. All nodes have just a single parent.
node:setPosition(x, y)Sets the position of the node.
node:setRotation(angle)Sets the rotation of the node.
node:setScale(sx, sy)Sets the scale of the node.
node:setTransform(x, y, angle)Sets the position and rotation of the node.
node:setVisible(True)Sets the visibility of the node. Non-visible nodes are not drawn at all.
node:windowToLocal(x, y)Converts a position from window to local coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
layer
layer.new(x, y, mt)This is an internal function. Please use scene.newLayer or layer.newLayer instead.
layer:clear()Removes all child nodes without destroying them.
layer:destroy()Destroys the layer and all of its child nodes.
layer:destroyChildren()Destroys all of the child nodes.
layer:draw()This is an internal function.
layer:getChild(index)Returns a child node based on depth index (could be negative).
layer:getChildDepth(child)Gets the depth index of a child node.
layer:insertChild(child)This is an internal function. Adds a new child node to the layer.
layer:newLayer(x, y)Creates a new layer at the given position.
layer:newSprite(x, y)Creates a new sprite at the given position.
layer:removeChild(child)This is an internal function. Removes an existing child node from the layer.
layer:setChildDepth(child, index)Sets the depth index of a child node. This depth index may shift as node are added, removed or sorted.
layer:sort(func)Sorts the child nodes based on a comparison function. If no comparison function is specified, nodes are sorted based on their Y-coordinates. This is useful in isometric or overhead games.

layer.new(x, y, mt)

This is an internal function. Please use scene.newLayer or layer.newLayer instead.
numberx
X coordinate
numbery
Y coordinate
tablemt (optional)
Metatable of base object
Returns
layer New layer

layer:clear()

Removes all child nodes without destroying them.

layer:destroy()

Destroys the layer and all of its child nodes.

layer:destroyChildren()

Destroys all of the child nodes.

layer:draw()

This is an internal function.

layer:getChild(index)

Returns a child node based on depth index (could be negative).
numberindex
Depth index

layer:getChildDepth(child)

Gets the depth index of a child node.
nodechild
Child node
Returns
number Depth index

layer:insertChild(child)

This is an internal function. Adds a new child node to the layer.
nodechild
Child node

layer:newLayer(x, y)

Creates a new layer at the given position.
numberx
X-coordinate
numbery
Y-coordinate
Returns
layer New layer object

layer:newSprite(x, y)

Creates a new sprite at the given position.
numberx
X-coordinate
numbery
Y-coordinate
Returns
sprite New sprite object

layer:removeChild(child)

This is an internal function. Removes an existing child node from the layer.
nodechild
Child node

layer:setChildDepth(child, index)

Sets the depth index of a child node. This depth index may shift as node are added, removed or sorted.
nodechild
Child node
numberindex
Depth index (could be negative)

layer:sort(func)

Sorts the child nodes based on a comparison function. If no comparison function is specified, nodes are sorted based on their Y-coordinates. This is useful in isometric or overhead games.
functionfunc (optional)
Comparison function



view

View is a clipped rectangular area where the scene is rendered. Views can be transformed, drawn and easily shaded.
node
node:compareDepth(other)Compares the depth of two nodes, based on their Y-coordinates.
node:getDepth()Gets the depth index relative to other nodes in the parent layer.
node:getPosition()Gets the position of the node.
node:getRoot()Returns the root layer of the node.
node:getRotation()Gets the rotation of the node.
node:getScale()Gets the scale of the node.
node:getTransform()Gets the position and rotation of the node.
node:getVisible()Gets the visibility of the node. Non-visible nodes are not drawn at all.
node:localToParent(x, y)Converts a position from local to parent coordinates. The center of the parent layer is its origin.
node:localToWindow(x, y)Converts a position from local to window coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
node:parentToLocal(x, y)Converts a position from parent to local coordinates. The center of the parent layer is its origin.
node:setDepth(index)Sets the depth index relative to other nodes in the parent layer. Setting the depth to 1 will draw the node first, before all others. Setting the depth to 0 will draw the node last, after all others. This depth index may shift as node are added, removed or sorted.
node:setParent(parent)Sets the parent layer of the node. All nodes have just a single parent.
node:setPosition(x, y)Sets the position of the node.
node:setRotation(angle)Sets the rotation of the node.
node:setScale(sx, sy)Sets the scale of the node.
node:setTransform(x, y, angle)Sets the position and rotation of the node.
node:setVisible(True)Sets the visibility of the node. Non-visible nodes are not drawn at all.
node:windowToLocal(x, y)Converts a position from window to local coordinates. This is useful because the mouse cursor is also in windows coordinates. The top left corner of the game window is its origin.
layer
layer:clear()Removes all child nodes without destroying them.
layer:destroyChildren()Destroys all of the child nodes.
layer:getChild(index)Returns a child node based on depth index (could be negative).
layer:getChildDepth(child)Gets the depth index of a child node.
layer:insertChild(child)This is an internal function. Adds a new child node to the layer.
layer:newLayer(x, y)Creates a new layer at the given position.
layer:newSprite(x, y)Creates a new sprite at the given position.
layer:removeChild(child)This is an internal function. Removes an existing child node from the layer.
layer:setChildDepth(child, index)Sets the depth index of a child node. This depth index may shift as node are added, removed or sorted.
layer:sort(func)Sorts the child nodes based on a comparison function. If no comparison function is specified, nodes are sorted based on their Y-coordinates. This is useful in isometric or overhead games.
view
view.new(x, y, width, height, mt)This is an internal function. Please use scene.newView instead.
view:destroy()Destroys the view and all of its children.
view:draw()Draws the view and all of its visible child nodes.
view:getBackground()Gets the background color.
view:getBounds()Gets the position and dimensions of the view inside the game window.
view:getDimensions()Gets the dimensions of the view inside the game window.
view:getScene()Gets the visible range in scene coordinates. The returned position is drawn in the center of the view.
view:getShader()Gets the pixel shader.
view:localToScene(x, y)Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.
view:sceneToLocal(x, y)Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.
view:sceneToWindow(x, y)Converts a position from scene to window coordinates. The origin of the scene is the center of the root layer.
view:setBackground(red, green, blue, alpha)Sets the background color.
view:setBounds(x, y, width, height)Sets the position and dimensions of the view inside the game window.
view:setDimensions(width, height)Sets the dimensions of the view inside the game window.
view:setScene(x, y, width, height)Sets the visible range in scene coordinates. The specified position will be drawn in the center of the view.
view:setShader(shader)Sets the pixel shader.
view:windowToScene(x, y)Converts a position from window to scene coordinates. The origin of the scene is the center of the root layer.

view.new(x, y, width, height, mt)

This is an internal function. Please use scene.newView instead.
numberx (optional)
X-position in pixels
numbery (optional)
Y-position in pixels
numberwidth (optional)
Width in pixels
numberheight (optional)
Height in pixels
tablemt (optional)
Metatable of base object
Returns
view New view object

view:destroy()

Destroys the view and all of its children.

view:draw()

Draws the view and all of its visible child nodes.

view:getBackground()

Gets the background color.
Returns
number Red value (0-1)
number Green value (0-1)
number Blue value (0-1)
number Alpha value (0-1)

view:getBounds()

Gets the position and dimensions of the view inside the game window.
Returns
number X-position in pixels
number Y-position in pixels
number Width in pixels
number Height in pixels

view:getDimensions()

Gets the dimensions of the view inside the game window.
Returns
number Width in pixels
number Height in pixels

view:getScene()

Gets the visible range in scene coordinates. The returned position is drawn in the center of the view.
Returns
number Scene X-coordinate
number Scene Y-coordinate
number Range width
number Range height

view:getShader()

Gets the pixel shader.
Returns
userdata Pixel shader object

view:localToScene(x, y)

Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.
numberx
Local X-coordinate
numbery
Local Y-coordinate
Returns
number Scene X-coordinate
number Scene Y-coordinate

view:sceneToLocal(x, y)

Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.
numberx
Scene X-coordinate
numbery
Scene Y-coordinate
Returns
number Local X-coordinate
number Local Y-coordinate

view:sceneToWindow(x, y)

Converts a position from scene to window coordinates. The origin of the scene is the center of the root layer.
numberx
X scene coordinate
numbery
Y scene coordinate
Returns
number X window coordinate
number Y window coordinate

view:setBackground(red, green, blue, alpha)

Sets the background color.
numberred
Red value (0-1)
numbergreen
Green value (0-1)
numberblue
Blue value (0-1)
numberalpha (optional)
Alpha value (0-1)

view:setBounds(x, y, width, height)

Sets the position and dimensions of the view inside the game window.
numberx
X-position in pixels
numbery
Y-position in pixels
numberwidth
Width in pixels
numberheight
Height in pixels

view:setDimensions(width, height)

Sets the dimensions of the view inside the game window.
numberwidth
Width in pixels
numberheight
Height in pixels

view:setScene(x, y, width, height)

Sets the visible range in scene coordinates. The specified position will be drawn in the center of the view.
numberx
Scene X-coordinate
numbery
Scene Y-coordinate
numberwidth (optional)
Range width
numberheight (optional)
Range height

view:setShader(shader)

Sets the pixel shader.
userdatashader (optional)
Pixel shader object

view:windowToScene(x, y)

Converts a position from window to scene coordinates. The origin of the scene is the center of the root layer.
numberx
X window coordinate
numbery
Y window coordinate
Returns
number X scene coordinate
number Y scene coordinate