LÖVE
Follow these steps to quickly set up and start using Planetary Processing with your LÖVE game. For more detailed information on both the SDK and the server-side API, please visit our documentation.
LÖVE Version
We recommend using LÖVE's most recent release version. If you are using an older version, we recommend a minimum of 11.0 for a successful integration.
Create a Planetary Processing Game
Navigate to the games section of our web panel
Click Create Game in the top right
Provide the details of your game. Upon its creation, you will be taken to your Game Dashboard.
For this quick start, we will be using Anonymous Auth, which allows players to connect without a username and password. To enable this, navigate to the settings section of your Game Dashboard and enable Anonymous Auth as the Player Authentication Type within Game Settings.
Clone your Game Repository
Clone the git repository as listed in your game dashboard - this is your Planetary Processing backend code.
git clone https://git.planetaryprocessing.io/git/aBcDE/my-planetary-processing-game.gitSetting Up Your LÖVE Project
In a separate directory, set up a new LÖVE project with at least a main.lua file.
Save an empty text document as
main.lua, in your chosen directory.Clone the Planetary Processing SDK into the same directory by running the following command:
git clone https://github.com/planetary-processing/love2d-sdk sdkSave a
conf.luafile in the same directory, with the following code for print() debugging to console.
-- enables printing to console
function love.conf(t)
t.console = true
end
Connecting to your game server
Edit
main.luato use the sdk. The sdk object can be used to interact with your game server.
-- use the Planetary Processing SDK
local sdk = require("sdk.sdk")Create a
love.load()function, containingsdk.init()andsdk.join(), to connect to the server and join as a player.Set the first parameter of
sdk.init()to be your Game Id. This is a number which can be found on your game dashboard, next to your game’s name and repo link.
--connect to the server
function love.load()
-- establish a connection to the game server
sdk.init(123)
-- join the game server with the player
sdk.join()
endCreate a
love.update(dt)function, withsdk.update()to receive data from the game server.
-- send, receive, and interpret data from the game server each frame
function love.update(dt)
-- get entity data and positions from the server
sdk.update()
endCreating Entities
While connected, the sdk will receive updated data about any entities visible to the player, and store it in sdk.entities. Entities are stored as tables which follow the format in the LÖVE SDK documentation.
Create a
love.draw()function, to display each entity.
-- display the entities, using their serverside positions
function love.draw()
-- draw each entity
for id,entity in pairs(sdk.entities) do
-- display each entity as a letter, using the position from the server
if entity.Type == "tree" then
love.graphics.print("T", entity.X, entity.Y)
elseif entity.Type == "cat" then
love.graphics.print("C", entity.X, entity.Y)
elseif entity.Type == "player" then
love.graphics.print("P", entity.X, entity.Y)
end
end
endTest your connection
You now have everything you need to establish a basic connection between LÖVE and the server-side demo code.
On the Planetary Processing games web panel, select your game to enter its dashboard.
Click Actions>Start Game to start the server-side simulation.
Run your
main.luafile using LÖVE.
You should be able to see all your entities displayed in a messy jumble in the top left of your game window. With the cats, or 'C's, slowly moving. Your Planetary Processing game dashboard map will also show that a player has joined!
Syncing the World Map and Window Origin
The Planetary Processing game world has its origin in the centre of the world, whereas LÖVE 's origin is in the top left of the game window. This can be resolved by displaying entities with an offset.
Create class variables in
main.luafor storing an X and Y offset.
-- for offsetting the centre of the world to window centre
local screenOffsetX = 0
local screenOffsetY = 0Set these variables in the start of
love.load().
-- create a custom game window and connect to the server
function love.load()
-- get the window width
window_width, window_height = love.graphics.getDimensions()
-- get the world coordinate offset
screenOffsetX = window_width/2
screenOffsetY = window_height/2Apply the offset before the entities are drawn each frame, at the start of
love.draw().
-- display the entities, using their serverside positions
function love.draw()
--apply the offset, to centre the world to the window
love.graphics.translate(screenOffsetX, screenOffsetY)Your viewport will now be centred on your game world's origin (0,0), where you can see the 'P' icon representing the player.
Syncing the World Map and Window Axis
LÖVE 's top left origin means that the game client's Y axis runs in the opposite direction to the game server's. Inverting any Y position values from the server will correct this.
Create a class variable in
main.luafor inverting the Y axis.
-- The Planetary Processing 'y' axis uses screen up, as the positive direction
-- Love2d uses screen down, as the positive direction
-- for inverting 'y' coordinate positions to and from the server
local invertYaxis = -1Apply that variable to each entity's Y value in
love.draw(), to correct its position.
-- display the entities, using their serverside positions
function love.draw()
--apply the offset, to centre the world to the window
love.graphics.translate(screenOffsetX, screenOffsetY)
-- draw each entity
for id,entity in pairs(sdk.entities) do
-- display each entity as a letter, using the position from the server
if entity.Type == "tree" then
love.graphics.print("T", entity.X, entity.Y * invertYaxis)
elseif entity.Type == "cat" then
love.graphics.print("C", entity.X, entity.Y * invertYaxis)
elseif entity.Type == "player" then
love.graphics.print("P", entity.X, entity.Y * invertYaxis)
end
end
endSyncing the World Map and Window Scale
The entity's coordinates are also currently using pixels, making everything display very close together. You can improve the viewport zoom by scaling the entity positions again.
Create a class variable in
main.luafor scaling the viewport zoom.
-- for scaling the viewport zoom
local zoom = 10Apply that variable to each entity's X and Y values in
love.draw(), to correct its position.
-- display the entities, using their serverside positions
function love.draw()
--apply the offset, to centre the world to the window
love.graphics.translate(screenOffsetX, screenOffsetY)
-- draw each entity
for id,entity in pairs(sdk.entities) do
-- display each entity as a letter, using the position from the server
if entity.Type == "tree" then
love.graphics.print("T",
entity.X * zoom,
entity.Y * zoom * invertYaxis)
elseif entity.Type == "cat" then
love.graphics.print("C",
entity.X * zoom,
entity.Y * zoom * invertYaxis)
elseif entity.Type == "player" then
love.graphics.print("P",
entity.X * zoom,
entity.Y * zoom * invertYaxis)
end
end
end
Player Movement
Now that the game world is visible and orientated, we can start interacting with it. We use sdk.message(msg) to send data to the player entity on the backend.
Edit the
love.update(dt)function, to send a table containing XY movement values to the server whenever a WASD input key is pressed.
-- send, receive, and interpret data from the game server each frame
function love.update(dt)
-- get entity data and positions from the server
sdk.update()
-- a message containing the changes in position
local move = {x=0, y=0}
-- for sending the move message on input
local sendMove = false
-- for dictating speed of movement
local speed = 10
-- on input, update the move message
if love.keyboard.isDown('w') then
move.y = move.y - speed*dt
sendMove = true
end
if love.keyboard.isDown('a') then
move.x = move.x - speed*dt
sendMove = true
end
if love.keyboard.isDown('s') then
move.y = move.y + speed*dt
sendMove = true
end
if love.keyboard.isDown('d') then
move.x = move.x + speed*dt
sendMove = true
end
-- if there is an input
if sendMove == true then
-- invert the y axis value
move.y = move.y * invertYaxis
-- send the move message to the game server
sdk.message(move)
end
endWhen this message is sent each frame, the player should now move both visibly in LÖVE and on the game dashboard map.
Follow Player Movement
To see the rest of our world, we can use the same world offsetting principle as before to show the world around the player.
Create class variables in
main.luafor storing an X and Y offset from the player's position.
-- for offsetting the viewport to centre on the player
local playerOffsetX = 0
local playerOffsetY = 0Get the player's position, to calculate the offset at the end of the
love.update(dt)function.
-- get the offset to centre the viewport on the player
for id,entity in pairs(sdk.entities) do
if id == sdk.uuid then
playerOffsetX = entity.X * zoom
playerOffsetY = entity.Y * zoom * invertYaxis
return
end
end Apply the player offset alongside the world position offset, in
love.draw().
-- display the entities, using their serverside positions
function love.draw()
-- apply the offset, to centre the world to the window,
-- and centre the viewport to be always on the player
love.graphics.translate(screenOffsetX - playerOffsetX,
screenOffsetY - playerOffsetY)
Resizing Your Window (Optional)
At this point you can start customising your LÖVE game client however you like. Take note that actions such as resizing the window will alter your world origin offset and must be corrected.
Set your window to resizable at the start of the
love.load()function.
-- create a custom game window and connect to the server
function love.load()
-- set the window options
love.window.setMode(0, 0, {resizable=true, vsync=1, minwidth=400, minheight=300})
-- maximise the window
love.window.maximize()Make a
love.resize()function, to get the new offset from the resized window.
-- update drawing position offsets, when window is resized
function love.resize()
-- get the window width
window_width, window_height = love.graphics.getDimensions()
-- get the world coordinate offset
screenOffsetX = window_width/2
screenOffsetY = window_height/2
endEditing Your Backend Code
Using the repo we cloned earlier you can edit the behaviour of entities by changing their Lua file within the entity directory.
You can also change how many and what entities are spawned in the init.lua file.
We recommend experimenting here to get a sense of what you can do with Planetary Processing. When you add or change entities, make sure your server-side changes match up with your game engine client.
Push Your Planetary Processing Backend Code to the Game Repository
After configuring your game entities and logic, push your changes to the game repository:
git add .
git commit -m "Configure game entities and logic for Planetary Processing"
git pushDeploy Latest Version in the Web UI
Go back to your game dashboard in our web panel.
From the actions menu in the top right, select "Deploy Latest Version" - this will roll out your updated server-side code.
Start Game in the Web UI
Click "Start Game" to begin your server-side simulation.
Play Your Multiplayer Game!
Launch your LÖVE project.
Connect to the multiplayer game through the game client, authenticate, and enjoy playing with others!
If you want to learn more about updating your server-side code, check out our server-side tutorial video: https://www.youtube.com/watch?v=QYWtedo1kr4&list=PLW5OY4K85Qhn7lwZeSPVZXH_Lg5IwhjNC
Troubleshooting
If you have encountered any issues, we have a premade demo of this guide: https://drive.google.com/drive/folders/1A7pIeFlghVxURlJEsGoiu0G1UGDuVwc6?usp=drive_link If you have further questions, please get in touch on our Discord.
Last updated