LÖVE

The LÖVE SDK integrates our multiplayer platform with LÖVE. The library provides methods and variables to use within your game client code - these communicate changes in state from your server side simulation to the game client itself.

If you are new here, we recommend starting with the LÖVE Quickstart Guide.

Pre-requisites

• LÖVE v11.0+

Installation

The LÖVE SDK can be installed by cloning the latest version from our GitHub into your a folder called sdk within your LÖVE game directory.

git clone https://github.com/planetary-processing/love2d-sdk sdk

You can then import the SDK like so:

local sdk = require(“sdk.sdk”)

SDK Object

The SDK object (the imported SDK) can be used to call a variety of functions. These allow you to connect to and pull information from the game server.

sdk.init

• Establish a connection

The first thing you need to do when your game starts is initialise the SDK. To do this, run the sdk.init function within love.load. This function takes the game_id parameter. The Game ID of your game can be found on the web panel.

Our LÖVE SDK only supports anonymous authentication at present, so you do not need supply a username and password.

function love.load()
    sdk.init(123)
end

sdk.join

• Join with a player

After a connection has been established by sdk.init, the function sdk.join will spawn the player into the game world.

function love.load()
    sdk.init(123)
    sdk.join()
end

sdk.update

• Receive server messages

The sdk.update function should be called within love.update. It will pass data about entities and chunks from the server to the client, then save it in the SDK object's variables.

function love.update(dt)
    sdk.update()
end

sdk.message

• Send messages to the server

You can call the sdk.message function to send a message to the server. This message will be received by the player.lua file's message function on the server.

sdk.message({x=1, y=-1})

sdk.server_to_client

• Receive manual server messages

The sdk.server_to_client variable can store a function. This function triggers when the client receives a message manually sent from the server by api.client.Message().

sdk.server_to_client = function (message)
    print(message)
end

Game World Objects

Game worlds are made up of entities, which represent objects and creatures, and chunks to represent the world space.

Entity Object

Data about entities is passed to the LÖVE client using sdk.update. You can access all the entities within sdk.entities (which can be iterated over) and draw them based each entity's data.

Entities have types used to categorise their behaviour on the server side backend. They can be used to access groups of entities. Individual entities can be accessed using the EntityID field.

The EntityID of the player entity associated with this client is also stored in sdk.uuid. This makes it easier to access the player entity directly with sdk.entities[sdk.uuid].

-- draw cat entities and player as 'C' and 'P' respectively
function love.draw()
	local player = sdk.entities[sdk.uuid]
	love.graphics.print("P", player.X, -player.Y)

	for id,entity in pairs(sdk.entities) do
		if entity.Type == "cat" then
			-- NOTE Planetary Processing's 'y' axis is inverted from LÖVE 
			love.graphics.print("C", entity.X, -entity.Y)
		end
	end
end

Chunk Object

Data about chunks is passed to the LÖVE client using sdk.update. You can access all the chunk data within sdk.chunks (which can be iterated over).

-- draw chunk borders when the chunk  size is 64
local chunk_size = 64

function love.draw()
    local world_x 
    local world_y 
    
    for id,chunk in pairs(sdk.chunks) do
        world_x = chunk.X * chunk_size
        world_y = chunk.Y * chunk_size
    
        love.graphics.line(world_x, world_y, world_x, world_y + chunk_size)
        love.graphics.line(world_x, world_y, world_x + chunk_size, world_y)
    end	
end

API

Below are reference tables of the API available within LÖVE 's environment.

The SDK exposes various public methods which can be accessed within scripts by importing the SDK like so:

local sdk = require(“sdk.sdk”)

To connect to the server and join with the player, for example:

sdk.init(123)
sdk.join()

SDK Object

Variables

Variable	Type	Description
entities	entities: table({ id: string entity: table )}	List of entities the client can see.
chunks	table: table({ id: string chunk: table )}	List of chunks the client can see.
uuid	string	UUID of the player associated with this client.
server_to_client	function(table)	Function which triggers, when a message is manually sent from the server to this player client.

Methods

Method	Parameters	Description
init	game_id: int	Called to connect to the Planetary Processing servers.
join	None	Spawn into the world.
update	None	Call this method inside love.update.
message	msg: table	Send a message to the player entity on the server.
leave	None	Disconnect the player from the world.
quit	None	Sever the connection to the game.

Entity Object

Fields

Field	Type	Description
EntityID	string	UUID of the entity.
X	float	X coordinate in world units.
Y	float	Y coordinate in world units.
Data	table	Data of the entity.
Type	string	Type of the entity.

Chunk Object

Fields

Field	Type	Description
ID	string	UUID of the chunk.
X	float	X coordinate in chunk units.
Y	float	Y coordinate in chunk units.
Data	table	Data of the chunk.