README.md
August 29, 2026 · View on GitHub
Note: This README covers development and contributing to the SDK. For end-user installation and usage, see the Documentation (Unity | MonoGame | Godot).
Setup
Unity
Run unity-setup.sh to fetch external dependencies (e.g. NativeWebSocket) into Assets/Colyseus/Runtime/WebSocket/:
bash unity-setup.sh
This is required before opening the project in Unity, and again whenever a new NativeWebSocket version ships — the script always clones the tip of the upm-2 branch, so re-running it is how you move to the latest.
It also points core.hooksPath at .githooks/, which installs a pre-push check that every asset under Assets/ has a committed .meta. Unity generates those locally, so a missing one is invisible from a clone — but it drops the file from the UPM branch and from the released .unitypackage. Run it by hand with ./scripts/check-meta.sh.
NuGet / Godot / MonoGame
External dependencies are resolved via NuGet packages — no setup script needed. The SDK is available as the Colyseus NuGet package, which depends on Colyseus.NativeWebSocket.
When the client is created on an engine main thread with a SynchronizationContext (Unity, Godot C#), WebSocket callbacks are marshaled back there automatically. Engines without one can register an external dispatcher through ColyseusContext.RegisterWebSocketForDispatch, or call room.Connection.DispatchMessageQueue() from their update loop.
Running the test server
In order to start a test server for this project's included example, do the following:
git clone https://github.com/colyseus/sdks-test-server
cd sdks-test-server
npm install
npm start
Running tests
dotnet test nuget/Colyseus.csproj
Releasing a new version
Update the version number under Assets/Colyseus/package.json and push to master branch.
License
MIT