Defold Engine

The Colyseus SDK for Defold supports all major platforms, including:

HTML5,
iOS,
Android
Native (Mac, and Windows.)

Install package

From your game.project file, add the following Dependencies to your project:

https://github.com/colyseus/colyseus-defold/archive/0.17.zip

https://github.com/defold/extension-websocket/archive/4.2.0.zip

Now, select Project ▸ Fetch Libraries to update library dependencies. Two folders with the library names should appear in your Defold project, indicating the libraries have been imported correctly.

Read more about Setting up library dependencies on Defold documentation.

SDK Example Project

The colyseus-defold repository contains a raw example project that demonstrates the SDK features. To run the example:

Clone the repository: git clone https://github.com/colyseus/colyseus-defold.git
Open the project in Defold Editor

Running the test server locally

To run the test server locally, you will need to run the following commands in your terminal:

Terminal

git clone https://github.com/colyseus/colyseus.git
cd colyseus
pnpm install
pnpm run sdk-test-server

⚠️

This test server is meant for testing features of the SDKs only. It does not follow good standards for production servers. For your own production servers, you should start from a fresh project and follow the Getting Started guide.

You can see the source code for the test server here.

You should be able to see the server running at http://localhost:2567, and the example project will be able to connect to it.

SDK API

Navigate to the Client SDK for API Reference, and select the Lua (Defold) tab.

FAQ

Defold Editor is not opening the project!

If you placed your server directory inside the Defold project directory, the Defold Editor might fail to load the project. You can fix this by adding the server directory to the .defignore file.

.defignore

/server

”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
        room:send("whatever")
    end
end
 
window.set_listener(window_callback)

Unity

Construct 3