Cocos Creator: How to add dedicated game servers in minutes, and Matchmaking to your multiplayer game

This guide shows you how to add dedicated game servers to a Cocos Creator multiplayer game and host them on Edgegap, then add matchmaking so players are grouped and connected to a server near them automatically.
Once your game server is containerized, Edgegap deploys it worldwide to 615+ Edge Cloud locations (on-demand) from a simple API call and billed exclusively on usage: no entire server to rent, provision or keep running between matches. For persistent servers of reserved capacity, Edgegap offers Private Fleets. Edgegap's Matchmaking builds on top of that and is optional.
Cocos Creator has no headless server build. A Cocos game's multiplayer server is a separate program, usually a Node.js app in a folder of your project: Colyseus, or your own WebSocket server. That server is what runs on Edgegap, and your Cocos project stays a normal client build. Each match gets its own server near its players, reached over wss://, and the server stops itself when the match is over.
This guide covers:
Preparing Cocos Creator, your server folder, your Edgegap account and Docker
Connecting your coding agent to Edgegap (optional)
Getting your game server ready for Edgegap
Building and uploading it with the Edgegap Cocos extension
Deploying a test server and connecting to it
Adding matchmaking (optional)
Shipping web and native builds
Testing the full loop with two players
You can do it two ways, and mix them:
With a coding agent. Connect Claude Code, Cursor or another agent to the Edgegap MCP server and its agent skills. The agent makes the server changes, sets up the extension and wires the matchmaker into your Cocos scripts. You sign in, click through the extension and playtest.
By hand. Every step below also works without an agent, with the Edgegap Cocos extension in the editor.
The guide uses Edgegap's fork of Colyseus's Cocos tic-tac-toe demo, upgraded to Cocos Creator 3.8.8 and Colyseus 0.17. It was tested on Edgegap on 29 October 2026 with a web build: matched through the matchmaker, played to the end, and the server stopped itself.
Which server does your game use?
Your game's server | How to follow this guide | Tested on Edgegap |
|---|---|---|
Colyseus | All steps, with the tic-tac-toe sample as a reference and the | Yes, with a web-desktop build (29 October 2026) |
Your own Node.js WebSocket server ( | The same steps, with the server and client templates of the | Templates run locally; not yet end to end on Edgegap |
Other languages work too: the server only needs to run in a Linux container.

Step-by-Step Guide
Detailed Integration Steps
1. Before you start
A free Edgegap account. Verify your email. No credit card is needed to test.
Cocos Creator 3.8 or newer. The sample uses 3.8.8.
Your game's server in a folder of your project (the extension looks in
Server/by default), with Node.js 22 for a Node.js server.Docker Desktop, running. The Edgegap Cocos extension runs on Windows and macOS.
For the agent path: an Edgegap API token, from Dashboard → User Settings → Tokens. It is organization-wide, so treat it like a password: never put it in a client, your server image or a chat.
Shortcut: run the sample first. Clone the tic-tac-toe fork, run
cd Server && npm install && npm start, then open the project in Cocos Creator 3.8.8 and run the preview (localhost:7456) in two browser tabs. Every change from step 3 is already in it.
2. Connect your coding agent to Edgegap
Skip this step if you're doing everything by hand.
The Edgegap MCP server lets your agent create apps and versions, deploy servers, read logs and generate matchmaker configurations on your account. Two skills cover Cocos Creator: edgegap-colyseus when your server is Colyseus (tested with the tic-tac-toe sample), and edgegap-cocos for any other server, with a server skeleton, the Cocos client files and the extension's settings.
Claude Code: install the Edgegap plugin. It adds both the MCP server and the skills, and asks for your API token during install (stored in your system's credential store):
/plugin marketplace add edgegap/llm-agent-skills, then /plugin install edgegap@edgegap. Restart the session.
Only want the MCP server, without the plugin? Run this in your own terminal instead: claude mcp add --transport http edgegap https://mcp.edgegap.dev/mcp -H "Authorization: token YOUR_EDGEGAP_API_TOKEN" --scope user. Don't do both, or you'll have two edgegap servers.
Cursor, VS Code and other clients that send headers: add https://mcp.edgegap.dev/mcp with the header Authorization: token YOUR_EDGEGAP_API_TOKEN, and install the skills with npx skills add edgegap/llm-agent-skills --skill "*".
Claude Desktop: custom connectors can't send the header, so use the local server instead (Node 22): { "mcpServers": { "edgegap": { "command": "npx", "args": ["-y", "@edgegap/mcp"] } } }. It asks for the token on first use.
Check it works:
"List my Edgegap apps."
3. Get your game server ready for Edgegap
Edgegap starts a server when a match needs one. Only your game knows when the match is over, so the server stops its own deployment. Otherwise an empty server keeps running, and billing, until its max duration.
Listen on the port from
PORT, on0.0.0.0, over WebSocket. Web builds served overhttps://can only openwss://. TLS Upgrade (step 4) handles the certificate, so your server speaks plainws.A lifecycle module that runs only on Edgegap (when
ARBITRIUM_REQUEST_IDis set, which Edgegap does on every deployment). It stops the deployment when nobody joined within 120 seconds, when the server has been empty for 30 seconds, or when the match ends. In the sample, it'sServer/src/edgegap.ts.End the match: lock the room, show the result for a few seconds, disconnect the players, then stop. Handle
SIGTERMtoo: tell the players and exit.Colyseus: keep the playground and monitor off on Edgegap: anyone with the server's address could open them. The sample mounts them only when it isn't running on Edgegap.
A Dockerfile in the server folder, with Node.js as the main process. The extension writes a starting one if you don't have it.
With your agent:
"Load the edgegap skill, then edgegap-colyseus (or edgegap-cocos if my server isn't Colyseus). Add the Edgegap lifecycle to my Cocos game's server in Server/: listen on PORT, stop the deployment when nobody joins, when everyone leaves and when a match ends, and handle SIGTERM. Then test it locally in Docker."
4. Build and upload your server
Edgegap runs your server inside a container. Use either option, or both.
Option A: the Edgegap Cocos extension. It builds, tests, uploads and deploys your server from one panel in the editor.
Install: download the extension and copy it into your project as
extensions/edgegap-extension/. It's prebuilt, so there's nothing to install. In Cocos Creator, open Extension → Extension Manager → Project and enable edgegap-extension, then open Extension → Edgegap → Open Panel.Sign in: select Get a token (one-click sign-in on the Edgegap dashboard), paste it and select Verify and sign in. The extension gets your registry login by itself. A regular API token works too: the panel then asks for the Project, Username and Token from the dashboard's Container Registry page. Both stay in your Cocos Creator user profile, never in the project.
Server: the server folder, image name, tag (a UTC timestamp, also used as the version name), port, protocol WS with TLS Upgrade on, and the port name
gameport. These settings are saved in the project, so your team shares them.Build image, then Run locally and point a client at
ws://localhost:<port>. Stop local when you're done.Push image and create version: pushes the image, creates the application if needed, and creates the version with your port, CPU, memory and max duration.
The extension doesn't set a restart policy or environment variables. After the first upload, open the version in the dashboard, set the restart policy to Never, and add any environment variables your server reads.
Option B: ask your agent.
"Build my Cocos game's server in Server/ for linux/amd64, push it to my Edgegap Container Registry with a new tag, and create the app and app version: my server's port, protocol WS, TLS Upgrade on, named gameport, 0.25 vCPU and 512 MB, restart policy never."
The agent asks you to run docker login registry.edgegap.com yourself, with the username and token from the Container Registry page, so those credentials stay out of the chat. Use a new image tag for every build, never latest.
For CI, the extension's scripts/e2e.mjs runs the same steps without the editor. To only ship builds, edgegap/deploy-action is simpler.
5. Deploy a test server and connect
In the panel, select Deploy near me. It starts one server close to your public IP address and shows the address clients connect to:
wss://<id>.pr.edgegap.net:<port>. Stop server stops it; it also stops on its own at the max duration.Pass the address to a client. In the sample's web build, add
?server=wss://...to the page address. Always use the host name, not the IP address, or the certificate check fails.If the first join fails with 502, retry: a server that has just started can answer 502 for a few seconds. The sample's
joinWithRetryretries 10 times, 2 seconds apart.
When the players leave, the server stops its own deployment and it disappears from the dashboard. The free tier runs one deployment at a time.
6. Add matchmaking
Edgegap's matchmaker groups players, deploys your server near them and gives every client its address.
Start from the sample's
edgegap/matchmaker-config.json: onecasualprofile of 2 players. Set the application version to the tag you uploaded.List your web addresses in
allowed_cors_origins: every address that serves your web build, plushttp://localhost:7456for the Cocos preview. Otherwise the browser blocks the matchmaker's replies.In the dashboard, open Matchmaker, select Create Matchmaker, upload the file and select Create and Start. Copy its API URL and Auth Token. The Auth Token is meant to ship in your game: it can only create and read matchmaking tickets. It is not your Edgegap API token.
In the sample: add
?mm=<API URL>&mmToken=<Auth Token>to the page address, or fill in the Matchmaker URL and Token fields of theSceneManagercomponent on the Canvas node.In your own project: copy the sample's
Matchmaker.tsandjoinWithRetry.tsinto your scripts and runnpm i @edgegap/sdk:Matchmaker.tsuses Edgegap's JavaScript SDK. Cancel the ticket when a player quits while searching.
With your agent:
"Using the edgegap-colyseus skill (or edgegap-cocos), add Edgegap matchmaking to my Cocos client: a casual profile of 2 players, my web addresses and localhost:7456 in allowed_cors_origins, a Find Match button, and a join that retries after the server is assigned."
By hand: see the Matchmaking documentation.
When you ship a new server build, update application.version in the matchmaker configuration (Stop, Edit, Start), or matches keep deploying the old build.
7. Ship web and native builds
Web (web-desktop, web-mobile): connect to
wss://by host name. Tested on Edgegap with a web-desktop build in Chrome; web-mobile wasn't run.Native (Windows, macOS, Android, iOS): Cocos Creator supports WebSockets in native builds, and since Cocos Creator 3.5,
wss://on Android no longer needs a certificate file. Native builds weren't run on Edgegap yet. If a Windows build fails the secure connection, pass a CA certificate bundle to the WebSocket. A game that ships only native builds can also use UDP or TCP ports, without TLS Upgrade.New server builds: in the panel, select Now for a new tag, then Build image and Push image and create version. Then point the matchmaker at the new version.
8. Test the full loop with two players
Make sure no test deployment is still running. On the free tier, a leftover one blocks the matchmaker's deployment.
Open two clients with the matchmaker settings: two web builds, or one web build and the sample's bot (
node scripts/e2e.mjs --players=1 --mm=<API URL> --mm-token=<Auth Token>inServer/, within 30 seconds).Keep the Cocos tab in front: a Cocos web build in a hidden tab runs no frames, so it never answers its turn.
Both players land on the same server and play. When the match ends, the server stops its own deployment and it disappears from the dashboard.
Before launch: set inspect to false in the matchmaker configuration, list only your real web addresses, raise the max duration to fit your matches, and let only matched players in (each matched deployment receives its ticket IDs in MM_TICKET_IDS).
On the free tier, the matchmaker stops 3 hours after each start (restart it from the dashboard), deployments stop after 60 minutes, and one deployment runs at a time.
Going live? Ask your agent to run the edgegap-launch skill's checklist.
Stuck? Ask your agent to load edgegap-troubleshoot, or ask our team and other studios on the Edgegap Discord.
Frequently Asked Questions
Common questions about hosting Cocos Creator multiplayer games on Edgegap's dedicated servers.
Does Cocos Creator build a dedicated server?
No. A Cocos Creator game's multiplayer server is a separate program, usually a Node.js app such as Colyseus or your own WebSocket server. Edgegap runs that program in a container, one server per match, near its players.
Which Cocos Creator versions work?
The Edgegap Cocos extension needs Cocos Creator 3.8 or newer, and the sample uses 3.8.8. The server side doesn't depend on your Cocos version: any server that runs in a Linux container works.
Can I use Colyseus with Cocos Creator on Edgegap?
Yes. Edgegap's fork of Colyseus's Cocos tic-tac-toe demo runs one Colyseus 0.17 server per match on Edgegap, started by the matchmaker, and was tested with a Cocos web build.
How do Cocos web builds connect to the server securely?
A page served over https:// can only open secure WebSockets (wss://). Turn on TLS Upgrade on the server's WS port: Edgegap handles the certificate and forwards plain traffic to your server. Connect by host name, not IP address.
Do I need the Edgegap Cocos extension?
No. It's the quickest way from the editor, but you can build and push with Docker and create the version in the dashboard, let your AI agent do it with the Edgegap MCP server, or ship builds from CI with edgegap/deploy-action.
Is the matchmaker token safe to ship in my game?
Yes. The matchmaker's Auth Token can only create and read matchmaking tickets. Your Edgegap API token controls your whole organization, so it never goes into a game client.

Clients
Learn more from clients who integrated Edgegap
31 case studies are available from studios that moved to Edgegap from another platform.

A Flawless Global Launch for Rivals of Aether 2
Aether Studios
Learn how Aether Studios quickly added Edgegap and delivered flawless launch & post-launch to their community.
Case Study

Overcome Latency Introduced by VR’s use of WiFi in Competitive Multiplayer
Halfbrick Studios
Discover how Halfbrick successfully launched & maintains a multiplayer-focused Early Access on META Quest's VR platform.
Case Study

MENA’s Social App Adds Online Games
WOLF
Learn how the highly popular MENA-region social app added matchmaking & multiplayer games orchestration easily to WOLF Qanawat.
Case Study

Hybrid Orchestration Keeps Kickoff Tactics Ready for Any Traffic
Birch Games
How hybrid orchestration helped Birch Games handle traffic, pairing egress-free Fleets with the regionless cloud.
Case Study

Authentic Online Warfare Requires the Ultimate Orchestration
Highwire Games
Learn how Highwire's need for performance required orchestration only Edgegap can deliver.
Case Study

22,000 Reviews, 4.8 Stars, and Infrastructure That Scaled Automatically
Sinn Studios
How a simple, Slack-supported integration got Sinn Studio's hit VR title online fast and keeps it there.
Case Study

Dynamic Server Orchestration
Under NDA - AAA Studio
Discover how one the world's biggest AAA studio improved its peer-to-peer multiplayer experience through edge computing.
Case Study

Near Zero Latency for AAA Fighting Game
AAA Studio - Under NDA
How an unannounced project delivered the lowest lag possible and improved fairness in its 1v1 game.
Case Study

Play Gods with Multiplayer Physics
Squido Studio
Learn how Squido uses Edgegap's highligh optimized game servers to deliver mind-bending & chaotic VR gameplay.
Case Study

A Fully Managed Solutions that Saves Time for Indies Multiplayer VR Horror
Dirty Pearl Studios
Discover how Dirty Pearl Studios saved development time thanks to Edgegap’s easy integration and automated orchestration alongside its Nakama integration.
Case Study

7 Days Blood Moons
The Fun Pimps & iLLOGIKA
Learn how Illogika dramatically reduced server costs & ensured the online experience the 7 Days to Die franchise expects.
Case Study

Instant Global Server Deployment for Collaborative XR Medical Education
AlensiaXR
How AlensiaXR uses Edgegap to deliver low-latency, always-available shared anatomy sessions to medical students worldwide.
Case Study

The Lightkeepers: A VR Social Co-op Game with Dedicated Servers
Spectral Games
How Spectral Games used Edgegap Matchmaking and Server Browser to launch dedicated servers for its VR social lobby, with no prior server experience.
Case Study

Fast & reliable deployments worldwide for PvPvE challenger Gravebound
Crater Studios
How Edgegap’s orchestration and matchmaking helped Crater Studios dramatically helped a small them focus on gameplay instead of infrastructure.
Case Study

Rapid Scaling of Web Metaverse
Hiber
Learn how Hiber eliminated the guesswork out of its server capacity planning with Edgegap.
Case Study

High Hardware Requirements & Custom Game Server Pools
Alderon Games
Learn how Alderon Games instantly leverages a custom pool of game servers across multiple providers worldwide for its popular MMO.
Case Study

Easy Integration for Indie Devs
WhaleFood Games
Read how WhaleFood Games "kicked out" its netcode issues with Edgegap.
Case Study

Cutting-edge tech that powers South-East Asia’s first-ever eSports title.
Anantarupa Studios
Learn how Edgegap transformed South-East Asia’s gaming landscape streamlining complex infrastructure and cutting-edge tech with one seamless solution.
Case Study

One Strike. Global Reach.
Triple Hill Interactive
How Triple Hill Interactive leverages Edgegap's orchestration to deliver low latency and improve fairness in a genre where every millisecond counts.
Case Study

Fast-paced Team Battle Royale... with Gun-totting Animal Plushes!
SANDYFLOOR
Discover how a Korea-based Indie Studio launched it multiplayer worldwide.
Case Study

Mobile Horse Racing Goes Global with Instant, Cost-Efficient Servers
Mirai Labs
How Mirai Labs powers Pegaxy Blaze's worldwide multiplayer races with just-in-time server deployment and fractional vCPU to keep cost per player low.
Case Study

Server Management & Distribution
Matrioshka Games
Read how Matrioshka Games were able to ship a Battle Royale in early access with limited ressources.
Case Study

At my Signal, Unleash Hell!
TyGames
Discover how Indie studio TyGames immerses players in third-person gladiatorial combat multiplayer.
Case Study

Instant Worldwide Orchestration
Soliton Interactive
Discover how Soliton Interactive did the impossible… Ship it's first playable as multiplayer!
Case Study

Competitive play with server-side physics ensures ideal sub-50 ms latency
NS7
Discover why solely Edgegap could enable an indie studio to deliver on its vision for a AAA-quality F2P sports gameplay through server-side physics and authority.
Case Study

Regional Deployments for iGaming
X1 Contra 1
X1 Contra 1 delivers real-time PvP casual games to its Brazilian player base through cost-effective hosting & regional deployments, ensuring data and legal compliance.
Case Study

Pay Only When Players Play: Affordable Multiplayer Infrastructure
Meltdown Interactive
How Edgegap helped indie developer Meltdown Interactive Media solve cost-effective scaling and matchmaking without the complexity, so they could focus on building the game.
Case Study

One Edgegap platform, three very different networking profiles
Warped Games
How Warped Games runs a social hub, real-time co-op, and turn-based co-op, all on the same Edgegap deployment API and the same container pipeline.
Case Study

Pool Live Tour Max
RETA Games
Case Study

Korea’s Web3 POP Extraction Shooter Goes Global, Instantly
NDUS Entertainment
How XOCIETY easily added Edgegap orchestration & integrated custom matchmaking working alongside Edgegap Ping Beacons to optimize latency.
Case Study

Multiplayer in Every Dimension
Arcadia.tv
Discover how Arcadia.tv uses Edgegap's edge network to deliver an innovative, team and location-based athletic VR sport.
Case Study

F2P Mobile Fighter Cuts Infrastructure Costs With Just-in-Time Servers
Game Changers Worldwide
How Game Changer Worldwide hosted Rumble Rush's real-time 3v3 PvP globally on mobile.
Case Study
Key reasons why they chose Edgegap
Discover the impact of Edgegap's automated game server orchestration for a flawless multiplayer experience.









