Skip to content

Defold SDK

Defold Engine is a Free 2D Game Engine for Cross-Platform Publishing.

The colyseus-defold SDK has been tested on all major platforms supported by Defold, such as HTML5, iOS, Android, Mac and Windows.


You will need to add colyseus-defold, as well as its dependencies into your game.project dependencies section in order to use the SDK.

Open your game.project file, and add the following URLs to the Dependencies section (under Project -> Dependencies):

Now, select Project ▸ Fetch Libraries to update library dependencies, two folders with the libraries name should pop up on your Defold project. This means the libraries have been imported correctly.

Read more about Defold library dependencies

You can also specify a specific release of the SDK, by copying its respective zip archive URL.


local ColyseusClient = require "colyseus.client"

local client
local room

function init(self)
    -- Add initialization code here
    client ="ws://localhost:2567")

    -- join chat room
    client:join_or_create("chat", {}, function(err, _room)
      if err then
        print("JOIN ERROR: " .. err)

      room = _room

See client-side documentation.


"I can't connect to the local server!"

When running on localhost, make sure you don't have any service running on port 80, otherwise the client won't connect into the specified port number.

Alternatively, you can bind the Colyseus server to port 80.

WSL2 Users

When running the colyseus server inside WSL2, you won't be able to use localhost as the hostname. You'll need to get the WSL2 machine's IP by using wsl hostname -I and use that IP.

"reconnect() is not working on iOS!"

If you lock your phone, all WebSocket connections will be closed. You can call reconnect() to reestablish the session, which needs a workaround for iOS:

function window_callback(self, event, data)
    if event == window.WINDOW_EVENT_FOCUS_GAINED then
        -- iOS workaround to re-active WebSocket connection after phone is unlocked