Introduction

love.scene is a two-dimensional scene graph library written for the LÖVE game framework (compatible with LÖVE 11.3, 11.4 and 11.5). To install the scene graph, copy the "scene" folder to your game directory and use require:

love.scene = require("scene")

The source code is available on GitHub and the official documentation is on 2dengine.com

Usage

The scene graph is fairly minimal, relying on just four different types of objects. Scene nodes are created using two different methods:

local view = love.scene.newView()
-- object-oriented style
local s1 = view:newSprite(0, 0)
-- Love2D style
local s2 = love.scene.newSprite(0, 0)
s2:setParent(view)

Images, text and other types of drawable graphics are rendered as follows:

-- image
local image = love.graphics.newImage("texture1.png")
s1:setGraphic(image)
-- text
local font = love.graphics.getFont()
local text = love.graphics.newText(font, "Hello world")
s2:setGraphic(text)

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

Nodes

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 modulated by changing their color, alpha value and blending mode.

local sprite = view:newSprite(0, 0)
-- draw
local image = love.graphics.newImage("myimage.png")
sprite:setGraphic(image)
-- transform
sprite:setPosition(100, 0)
sprite:setRotation(math.pi/2)
sprite:setScale(1, 2)
-- modulate
sprite:setColor(1, 0, 0)
sprite:setAlpha(0.5)
sprite:setMode("add")

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.

local root = view:newLayer(0, 0)
local a = root:newSprite(0, 0)
local b = root:newSprite(0, 0)
a:setGraphic(love.graphics.newImage('background.png'))
b:setGraphic(love.graphics.newImage('foreground.png'))
-- modify drawing order
b:setDepth(1)

View

View is a clipped rectangular area inside the application window where the scene is rendered. Views can be transformed, drawn and easily shaded.

local view = love.scene.newView()
-- shading
local shader = love.graphics.newShader([[ vec4 effect( vec4 c, Image t, vec2 tc, vec2 sc ){
  vec4 p = Texel(t, tc );
  number a = (p.r+p.b+p.g)/3.0;
  number f = tc.x;
  p.r = p.r + (a - p.r)*f;
  p.g = p.g + (a - p.g)*f;
  p.b = p.b + (a - p.b)*f;
  return p;
} ]])
view:setShader(shader)

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

Camera

Cameras can be transformed just like regular nodes and can also render their surroundings onto a view object.

local view = love.scene.newView()
local root = love.scene.newLayer(0, 0)
local cam = root:newCamera(100, 0)
cam:setRange(800, 400)
view:setCamera(cam)

love.scene > scene

scene

This is the main module of the scene graph library. The scene. module is used to create new nodes.

scene.copy(src, dest)

scene.destroy(t)

scene.new(t, ...)

scene.newCamera(x, y)

scene.newLayer(x, y)

scene.newSprite(x, y)

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

scene.copy(src, dest)

This is an internal function

	Arguments
node	src Source node
node	dest Destination node

scene.destroy(t)

This is an internal function

	Arguments
node	t Existing node

See: node:destroy

scene.new(t, ...)

This is an internal function

	Arguments
node	t Existing node
arguments	... Constructor arguments
	Returns
node	New node object

See: scene.newSprite, scene.newCamera, scene.newLayer, scene.newView

scene.newCamera(x, y)

Creates a new camera object. Alternatively, you can use layer:newCamera.

	Arguments
number	x X coordinate
number	y Y coordinatex
	Returns
camera	New camera object

See: layer:newCamera

scene.newLayer(x, y)

Creates a new layer object. Alternatively, you can use layer:newLayer.

	Arguments
number	x X coordinate
number	y Y coordinate
	Returns
layer	New layer object

See: layer:newLayer

scene.newSprite(x, y)

Creates a new sprite object. Alternatively, you can use layer:newSprite.

	Arguments
number	x X coordinate
number	y Y coordinate
	Returns
sprite	New sprite object

See: layer: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.

	Arguments
number	x (optional) X-position in pixels
number	y (optional) Y-position in pixels
number	width (optional) Width in pixels
number	height (optional) Height in pixels
	Returns
view	New view object

love.scene > node

node

This is an abstract scene graph node that supports transformations and hierarchy.

node.construct(x, y)

node:compareDepth(other)

node:localToParent(x, y)

node:localToRoot(x, y)

node:localToWindow(x, y)

node:parentToLocal(x, y)

node:reset(x, y)

node:rootToLocal(x, y)

node:setDepth(index)

node:setParent(parent)

node:setPosition(x, y)

node:setRotation(angle)

node:setScale(sx, sy)

node:setTransform(x, y, angle)

node:setVisible(True)

node:type()

node:windowToLocal(x, y)

node.construct(x, y)

This is an internal function

	Arguments
number	x X-coordinate
number	y Y-coordinate
	Returns
node	New node

node:compareDepth(other)

This is an internal function. Compares the depth of two nodes, based on their Y-coordinates.

	Arguments
node	other Other other
	Returns
boolean	True if this node is in front of the other

node:deconstruct()

This is an internal function

See: node:destroy

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

See: node:setDepth

node:getParent()

Gets the current parent layer of the node.

	Returns
layer	Current parent layer

node:getPosition()

Gets the position of the node.

	Returns
number	X-coordinate
number	Y-coordinate

See: node:setPosition

node:getRoot()

Returns the root layer of the node or nil if the current node does not have a parent.

	Returns
layer	Root layer

node:getRotation()

Gets the rotation of the node.

	Returns
number	Angle in radians

See: node:setRotation

node:getScale()

Gets the scale of the node.

	Returns
number	X-axis scale
number	Y-axis scale

See: node:setScale

node:getTransform()

Gets the position and rotation of the node.

	Returns
number	X-coordinate
number	Y-coordinate
number	Angle in radians

See: node:setTransform

node:getVisible()

Gets the visibility of the node. Non-visible nodes are not drawn at all.

	Returns
boolean	True if visible

See: node:setVisible

node:localToParent(x, y)

Converts a position from local to parent coordinates. The center of the parent layer is its origin.

	Arguments
number	x Local X-coordinate
number	y Local Y-coordinate
	Returns
number	Parent X-coordinate
number	Parent Y-coordinate

See: node:parentToLocal

node:localToRoot(x, y)

Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.

	Arguments
number	x Local X-coordinate
number	y Local Y-coordinate
	Returns
number	Scene X-coordinate
number	Scene Y-coordinate

See: node:rootToLocal

node:localToWindow(x, y)

Converts a position from local to window coordinates. This function works only if the root node is a view object or returns nil otherwise.

	Arguments
number	x Local X-coordinate
number	y Local Y-coordinate
	Returns
number	Window X-coordinate
number	Window Y-coordinate

See: node:windowToLocal

node:parentToLocal(x, y)

Converts a position from parent to local coordinates. The center of the parent layer is its origin.

	Arguments
number	x Parent X-coordinate
number	y Parent Y-coordinate
	Returns
number	Local X-coordinate
number	Local Y-coordinate

See: node:localToParent

node:reset(x, y)

This is an internal function

	Arguments
number	x X-coordinate
number	y Y-coordinate

node:rootToLocal(x, y)

Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.

	Arguments
number	x Scene X-coordinate
number	y Scene Y-coordinate
	Returns
number	Local X-coordinate
number	Local Y-coordinate

See: node:localToRoot

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 nodes are added, removed or sorted.

	Arguments
number	index Depth index (could be negative)

See: node:getDepth, layer:sort

node:setParent(parent)

Sets the parent layer of the node. All nodes can have just one parent.

	Arguments
layer	parent New parent layer

node:setPosition(x, y)

Sets the position of the node.

	Arguments
number	x X-coordinate
number	y Y-coordinate

See: node:getPosition

node:setRotation(angle)

Sets the rotation of the node.

	Arguments
number	angle Angle in radians

See: node:getRotation

node:setScale(sx, sy)

Sets the scale of the node.

	Arguments
number	sx X-axis scale
number	sy Y-axis scale

See: node:getScale

node:setTransform(x, y, angle)

Sets the position and rotation of the node.

	Arguments
number	x X-coordinate
number	y Y-coordinate
number	angle Angle in radians

See: node:getTransform

node:setVisible(True)

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

	Arguments
boolean	True if visible

See: node:getVisible

node:type()

Returns the node type as a string

	Returns
string	Node type ("Sprite", "Layer" or "View").

node:windowToLocal(x, y)

Converts a position from window to local coordinates. This function works only if the root node is a view object or returns nil otherwise.

	Arguments
number	x Window X-coordinate
number	y Window Y-coordinate
	Returns
number	Local X-coordinate
number	Local Y-coordinate

See: node:localToWindow

love.scene > sprite

sprite

Functions inherited from "node"
node:compareDepth(other)
node:destroy()
node:getDepth()
node:getParent()
node:getPosition()
node:getRoot()
node:getRotation()
node:getScale()
node:getTransform()
node:getVisible()
node:localToParent(x, y)
node:localToRoot(x, y)
node:localToWindow(x, y)
node:parentToLocal(x, y)
node:rootToLocal(x, y)
node:setDepth(index)
node:setParent(parent)
node:setPosition(x, y)
node:setRotation(angle)
node:setScale(sx, sy)
node:setTransform(x, y, angle)
node:setVisible(True)
node:type()
node:windowToLocal(x, y)
Functions
sprite.construct(x, y)
sprite:deconstruct()
sprite:draw()
sprite:getAlpha()
sprite:getColor()
sprite:getGraphic()
sprite:getMode()
sprite:getShader()
sprite:reset(x, y)
sprite:setAlpha(alpha)
sprite:setColor(red, green, blue)
sprite:setGraphic(drawable, quad, x, y, angle, sx, sy, ox, oy, kx, ky)
sprite:setMode(mode)
sprite:setShader(shader)

sprite.construct(x, y)

This is an internal function Please use scene.newSprite or layer.newSprite instead.

	Arguments
number	x X coordinate
number	y Y coordinate
	Returns
sprite	New sprite

See: layer:newSprite, scene.newSprite

sprite:deconstruct()

This is an internal function

See: node:destroy

sprite:draw()

This is an internal function

See: view:draw

sprite:getAlpha()

Gets the alpha value.

	Returns
number	Alpha value (0-1)

See: sprite:setAlpha

sprite:getColor()

Gets the color.

	Returns
number	Red value (0-1)
number	Green value (0-1)
number	Blue value (0-1)

See: sprite:setColor

sprite:getGraphic()

Gets the "drawable" graphic and quad of the sprite.

	Returns
userdata	Drawable graphic
userdata	Quad or nil

See: sprite:setGraphic

sprite:getMode()

Gets the blending mode.

	Returns
string	mode Blend mode

See: sprite:setMode

sprite:getShader()

Gets the shader used when drawing the sprite.

	Returns
userdata	Shader object

See: sprite:getShader

sprite:reset(x, y)

Resets the node to its initial state.

	Arguments
number	x X-coordinate
number	y Y-coordinate

sprite:setAlpha(alpha)

Sets the alpha value.

	Arguments
number	alpha Alpha value (0-1)

See: sprite:getAlpha

sprite:setColor(red, green, blue)

Sets the color.

	Arguments
number	red Red value (0-1)
number	green Green value (0-1)
number	blue Blue value (0-1)

See: sprite:getColor

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.

	Arguments
userdata	drawable Drawable graphic
userdata	quad (optional) Optional quad
number	x (0) X coordinate
number	y (0) y coordinate
number	angle (0) Angle
number	sx (1) X axis scale
number	sy (1) Y axis scale
number	ox (0) X axis offset
number	oy (0) Y axis offset
number	kx (0) X axis shearing
number	ky (0) Y axis shearing

See: sprite:getGraphic

sprite:setMode(mode)

Sets the blending mode.

	Arguments
string	mode Blend mode: "alpha", "add", "subtract" or "multiply"

See: sprite:getMode

sprite:setShader(shader)

Sets the shader used when drawing the sprite.

	Arguments
userdata	shader Shader object

See: sprite:getShader

love.scene > layer

layer

Functions inherited from "node"
node:compareDepth(other)
node:destroy()
node:getDepth()
node:getParent()
node:getPosition()
node:getRoot()
node:getRotation()
node:getScale()
node:getTransform()
node:getVisible()
node:localToParent(x, y)
node:localToRoot(x, y)
node:localToWindow(x, y)
node:parentToLocal(x, y)
node:rootToLocal(x, y)
node:setDepth(index)
node:setParent(parent)
node:setPosition(x, y)
node:setRotation(angle)
node:setScale(sx, sy)
node:setTransform(x, y, angle)
node:setVisible(True)
node:type()
node:windowToLocal(x, y)
Functions
layer.construct(x, y)
layer:deconstruct()
layer:destroyChildren()
layer:draw()
layer:getChild(index)
layer:getChildDepth(child)
layer:insertChild(child)
layer:newCamera(x, y)
layer:newLayer(x, y)
layer:newSprite(x, y)
layer:removeChild(child)
layer:removeChildren()
layer:reset(x, y)
layer:setChildDepth(child, index)
layer:sort(func)

layer.construct(x, y)

This is an internal function Please use scene.newLayer or layer.newLayer instead.

	Arguments
number	x X coordinate
number	y Y coordinate
	Returns
layer	New layer

See: layer:newLayer, scene.newLayer

layer:deconstruct()

This is an internal function

See: node:destroy

layer:destroyChildren()

Destroys all of the child nodes.

layer:draw()

This is an internal function

See: view:draw

layer:getChild(index)

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

	Arguments
number	index Depth index

layer:getChildDepth(child)

Gets the depth index of a child node.

	Arguments
node	child Child node
	Returns
number	Depth index

layer:insertChild(child)

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

	Arguments
node	child Child node

layer:newCamera(x, y)

Creates a new camera at the given position. Sets the parent of the new camera to the current node.

	Arguments
number	x X-coordinate
number	y Y-coordinate
	Returns
camera	New camera object

layer:newLayer(x, y)

Creates a new layer at the given position. Sets the parent of the new layer to the current node.

	Arguments
number	x X-coordinate
number	y Y-coordinate
	Returns
layer	New layer object

layer:newSprite(x, y)

Creates a new sprite at the given position. Sets the parent of the new sprite to the current node.

	Arguments
number	x X-coordinate
number	y Y-coordinate
	Returns
sprite	New sprite object

layer:removeChild(child)

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

	Arguments
node	child Child node

layer:removeChildren()

Removes all child nodes without destroying them.

layer:reset(x, y)

This is an internal function

	Arguments
number	x X-coordinate
number	y Y-coordinate

layer:setChildDepth(child, index)

Sets the depth index of a child node. This depth index may shift as node are added, removed or sorted.

	Arguments
node	child Child node
number	index 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.

	Arguments
function	func (optional) Comparison function

love.scene > camera

camera

Cameras can be placed in the scene and transformed like regular nodes. Cameras can also render contents onto the view object.

Functions inherited from "node"
node:compareDepth(other)
node:deconstruct()
node:destroy()
node:getDepth()
node:getParent()
node:getPosition()
node:getRoot()
node:getRotation()
node:getScale()
node:getTransform()
node:getVisible()
node:localToParent(x, y)
node:localToRoot(x, y)
node:localToWindow(x, y)
node:parentToLocal(x, y)
node:rootToLocal(x, y)
node:setDepth(index)
node:setParent(parent)
node:setPosition(x, y)
node:setRotation(angle)
node:setScale(sx, sy)
node:setTransform(x, y, angle)
node:setVisible(True)
node:type()
node:windowToLocal(x, y)
Functions
camera.construct(x, y)
camera:draw()
camera:getRange()
camera:render(view)
camera:reset(x, y)
camera:setRange(width, height)

camera.construct(x, y)

This is an internal function Please use scene.newCamera or layer.newCamera instead.

	Arguments
number	x X coordinate
number	y Y coordinate
	Returns
camera	New camera

See: layer:newCamera, scene.newCamera

camera:draw()

This is an internal function

camera:getRange()

Gets the viewing range of the camera in scene units. Returns zero if no range is specified.

	Returns
number	Range width in scene units
number	Range height in scene units

See: camera:setRange

camera:render(view)

This is an internal function

	Arguments
node	view View object

See: view:draw

camera:reset(x, y)

This is an internal function

	Arguments
number	x X-coordinate
number	y Y-coordinate

camera:setRange(width, height)

Sets the viewing range of the camera in scene units. The camera node's scale is ignored upon setting a non-zero range. When the viewing range is set to zero, the rendered area is determined by the camera's scale and the dimensions of the view object.

	Arguments
number	width Range width in scene units
number	height Range height in scene units

See: camera:getRange

love.scene > view

view

View is a clipped rectangular area inside the application window where the scene is rendered. Views can be transformed, drawn and shaded.

Functions inherited from "node"
node:compareDepth(other)
node:destroy()
node:getDepth()
node:getParent()
node:getRoot()
node:getRotation()
node:getScale()
node:getTransform()
node:getVisible()
node:localToParent(x, y)
node:parentToLocal(x, y)
node:setDepth(index)
node:setParent(parent)
node:setRotation(angle)
node:setScale(sx, sy)
node:setTransform(x, y, angle)
node:setVisible(True)
node:type()
Functions inherited from "layer"
layer:destroyChildren()
layer:getChild(index)
layer:getChildDepth(child)
layer:insertChild(child)
layer:newCamera(x, y)
layer:newLayer(x, y)
layer:newSprite(x, y)
layer:removeChild(child)
layer:removeChildren()
layer:setChildDepth(child, index)
layer:sort(func)
Functions
view.construct(x, y, width, height)
view:deconstruct()
view:draw()
view:getBackground()
view:getCamera()
view:getDimensions()
view:getOrigin()
view:getPosition()
view:getShader()
view:localToRoot(x, y)
view:localToWindow(x, y)
view:reset(x, y, width, height)
view:rootToLocal(x, y)
view:rootToWindow(x, y)
view:setBackground(red, green, blue, alpha)
view:setCamera(camera)
view:setDimensions(width, height)
view:setOrigin(ox, oy)
view:setPosition(x, y)
view:setShader(shader)
view:windowToLocal(x, y)
view:windowToRoot(x, y)

view.construct(x, y, width, height)

This is an internal function Please use scene.newView instead.

	Arguments
number	x (optional) X-position in pixels
number	y (optional) Y-position in pixels
number	width (optional) Width in pixels
number	height (optional) Height in pixels
	Returns
view	New view object

See: scene.newView

view:deconstruct()

This is an internal function

See: node:destroy

view:draw()

By default, this function 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)

See: view:setBackground

view:getCamera()

Gets the camera associated with the view.

	Returns
camera	camera Camera object

See: view:setCamera

view:getDimensions()

Gets the dimensions of the view inside the game window.

	Returns
number	Width in pixels
number	Height in pixels

See: view:setDimensions

view:getOrigin()

Gets the origin of the view object as ratio values, where 0, 0 is the top-left corner and 1, 1 is the bottom right. The origin of the view is the center or 0.5, 0.5.

	Returns
number	X-ratio from 0 to 1
number	Y-ratio from 0 to 1

See: view:setOrigin

view:getPosition()

Gets the position of the view inside the application window.

	Returns
number	X-position in pixels
number	Y-position in pixels

view:getShader()

Gets the pixel shader.

	Returns
userdata	Pixel shader object

See: view:setShader

view:localToRoot(x, y)

Converts a position from local to scene coordinates. The origin of the scene is the center of the root layer.

	Arguments
number	x Local X-coordinate
number	y Local Y-coordinate
	Returns
number	Scene X-coordinate
number	Scene Y-coordinate

See: view:rootToLocal

view:localToWindow(x, y)

Converts a position from scene to window coordinates. The origin of the scene is the center of the root layer.

	Arguments
number	x X scene coordinate
number	y Y scene coordinate
	Returns
number	X-position in pixels
number	Y-position in pixels

See: view:windowToLocal

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

This is an internal function

	Arguments
number	x X-position in pixels
number	y Y-position in pixels
number	width Width in pixels
number	height Height in pixels

view:rootToLocal(x, y)

Converts a position from scene to local coordinates. The origin of the scene is the center of the root layer.

	Arguments
number	x Scene X-coordinate
number	y Scene Y-coordinate
	Returns
number	Local X-coordinate
number	Local Y-coordinate

See: view:localToRoot

view:rootToWindow(x, y)

Converts scene coordinates to window coordinates. This function works in conjunction with the currently associated camera.

	Arguments
number	x X scene coordinate
number	y Y scene coordinate
	Returns
number	X-position in pixels
number	Y-position in pixels

See: view:windowToLocal

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

Sets the background color.

	Arguments
number	red Red value (0-1)
number	green Green value (0-1)
number	blue Blue value (0-1)
number	alpha (optional) Alpha value (0-1)

See: view:getBackground

view:setCamera(camera)

Sets the camera for the view.

	Arguments
camera	camera Camera object

See: view:getCamera

view:setDimensions(width, height)

Sets the dimensions of the view inside the game window.

	Arguments
number	width Width in pixels
number	height Height in pixels

See: view:getDimensions

view:setOrigin(ox, oy)

Sets the origin of the view object based ratio values, where 0, 0 is the top-left corner and 1, 1 is the bottom right. The default origin of the view is the center or 0.5, 0.5.

	Arguments
number	ox X-ratio from 0 to 1
number	oy Y-ratio from 0 to 1

See: view:getOrigin

view:setPosition(x, y)

Sets the position of the view inside the application window.

	Arguments
number	x X-position in pixels
number	y Y-position in pixels

view:setShader(shader)

Sets the pixel shader.

	Arguments
userdata	shader (optional) Pixel shader object

See: view:getShader

view:windowToLocal(x, y)

Converts a position from window to scene coordinates. The origin of the scene is the center of the root layer.

	Arguments
number	x X-position in pixels
number	y Y-position in pixels
	Returns
number	X scene coordinate
number	Y scene coordinate

See: view:localToWindow

view:windowToRoot(x, y)

Converts window coordinates to scene coordinates. This function works in conjunction with the currently associated camera.

	Arguments
number	x X-position in pixels
number	y Y-position in pixels
	Returns
number	X scene coordinate
number	Y scene coordinate

See: view:windowToLocal