Information Eggy Swarm: Node.js & PM2 Multiplayer Setup Guide

[Eggy]

Eggy Swarm: Node.js & PM2 Multiplayer Setup Guide​

Eggy Swarm uses a Node.js realtime service to power multiplayer sessions between players.

The main Swarm game, Story Mode, challenges, achievements and other single-player features do not require Node.js. This guide is specifically for setting up realtime multiplayer.

For most installations, the recommended configuration is:

Node.js host: 127.0.0.1
Node.js port: 31338
Public WebSocket path: /swarm-realtime

The Node.js service remains private on the server while players connect through your normal website using the /swarm-realtime WebSocket path.

Requirements​

Before starting, you will need:

• SSH access to your server
• Node.js installed
• npm installed
• PM2 installed
• Access to your web server or hosting control panel
• Eggy Swarm installed
• Multiplayer enabled in the Eggy Swarm ACP

Node.js 20 or newer is recommended.

1. Check Node.js and npm​

Connect to your server through SSH and run:

node -v
npm -v

You should see version numbers returned.

For example:

v20.x.x
10.x.x

If either node or npm cannot be found, install Node.js before continuing.

Your hosting provider may already provide a supported method for installing Node.js.

2. Find the Eggy Swarm realtime directory​

Go to:

Admin control panel → Eggy Swarm → Multiplayer

Swarm displays the exact realtime service directory for your installation.

It will look similar to:

/var/www/vhosts/example.com/httpdocs/src/addons/Eggy/Swarm/Realtime

Use the directory displayed on your own server.

For example:

cd /var/www/vhosts/example.com/httpdocs/src/addons/Eggy/Swarm/Realtime

Replace example.com with your own domain/path.

3. Install the Node.js dependencies​

While inside the Swarm Realtime directory, run:

npm ci --omit=dev

This installs the production dependencies required by the bundled Eggy Swarm realtime service.

Once completed, check the supplied Node.js application:

npm run check

There should be no JavaScript syntax errors.

4. Install PM2​

PM2 keeps the Eggy Swarm realtime service running after you disconnect from SSH.

It can also restart the service automatically if required and restore it after a server reboot.

Install PM2 globally:

npm install -g pm2

Confirm PM2 is installed:

pm2 -v

A PM2 version number should be returned.

5. Configure Eggy Swarm multiplayer​

Return to:

Admin control panel → Eggy Swarm → Multiplayer

For a normal installation where XenForo and Node.js are running on the same server, use:

Enable multiplayer: Yes

Node.js host:
127.0.0.1

Node.js port:
31338

Swarm will also display:

Public WebSocket path:
/swarm-realtime

You should also see:

Realtime secret: Ready

Save the multiplayer settings.

6. About the realtime secret​

Eggy Swarm generates a unique realtime secret for each installation.

You normally do not need to manually enter or copy this secret.

The bundled Node.js service reads the secret generated by Eggy Swarm from your XenForo installation.

If you use the Regenerate realtime secret option in the Swarm ACP, restart the realtime service afterwards:

pm2 restart eggy-swarm-realtime

7. Start Eggy Swarm using PM2​

Return to the Swarm realtime directory:

cd /var/www/vhosts/example.com/httpdocs/src/addons/Eggy/Swarm/Realtime

Start the service:

EGGY_SWARM_HOST=127.0.0.1 EGGY_SWARM_PORT=31338 pm2 start server.js --name eggy-swarm-realtime

Now check the PM2 process list:

pm2 status

You should see:

eggy-swarm-realtime

with the status:

online

8. Test the Node.js service directly​

Before configuring the public WebSocket proxy, make sure the Node.js service itself is responding correctly.

Run:

curl -sS http://127.0.0.1:31338/health

A healthy Eggy Swarm realtime service should return a successful JSON response containing something similar to:

"ok":true

You can also test the connection directly from Eggy Swarm.

Go to:

Admin control panel → Eggy Swarm → Multiplayer

Click:

Test realtime connection

A successful test should display:

Connected

and:

Realtime service responded successfully.

If this test fails, do not continue to the WebSocket proxy stage yet.

First make sure Node.js and PM2 are running correctly.

9. Configure the public WebSocket proxy​

This is an important part of the setup.

Players do not connect directly to:

127.0.0.1:31338

That address should normally remain private.

Players connect through your website using:

/swarm-realtime

Your web server therefore needs to proxy:

https://yourdomain.com/swarm-realtime

to:

http://127.0.0.1:31338

The connection flow is:

Player browser
      ↓
yourdomain.com/swarm-realtime
      ↓
Web server / reverse proxy
      ↓
127.0.0.1:31338
      ↓
Eggy Swarm realtime service

10. Plesk / nginx setup​

If your server uses Plesk with nginx, go to:

Websites & Domains → Your domain → Apache & nginx Settings

Find:

Additional nginx directives

Add:

location /swarm-realtime {
    proxy_pass http://127.0.0.1:31338;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
}

Save/apply the configuration.

This allows WebSocket traffic arriving through /swarm-realtime to reach the internal Eggy Swarm Node.js service.

11. Other web servers​

If you use Apache, LiteSpeed, nginx without Plesk, or another reverse proxy, configure the equivalent WebSocket proxy.

The required route is:

/swarm-realtime
        ↓
127.0.0.1:31338

Your proxy must support WebSocket upgrade requests.

The important WebSocket headers are:

Upgrade
Connection

If you are unsure how to configure WebSocket proxying on your hosting setup, contact your hosting provider and ask them to proxy:

/swarm-realtime

to:

127.0.0.1:31338

with WebSocket support enabled.

12. Cloudflare users​

Eggy Swarm can work through Cloudflare.

You should normally leave Node.js listening only on:

127.0.0.1:31338

Do not expose port 31338 publicly just because you use Cloudflare.

The player's browser should connect through:

wss://yourdomain.com/swarm-realtime

The expected connection route is:

Player
   ↓
Cloudflare
   ↓
Your website
   ↓
/swarm-realtime
   ↓
127.0.0.1:31338
   ↓
Eggy Swarm realtime service

If the ACP connection test works but multiplayer does not, check that Cloudflare or another security service is not blocking WebSocket requests to:

/swarm-realtime

13. Make PM2 survive a server reboot​

Once the realtime service is running correctly, save the PM2 process list:

pm2 save

Then run:

pm2 startup

PM2 will normally display another command specific to your operating system and server user.

Copy and run the command PM2 gives you.

Afterwards, save the process list again:

pm2 save

This allows the Eggy Swarm realtime service to automatically return after a server reboot.

14. Final multiplayer test​

Return to:

Admin control panel → Eggy Swarm → Multiplayer

The connection status should show:

Connected

Now perform a proper multiplayer test using two separate XenForo accounts.

Ideally use two different browsers or devices.

Both players should:

• Open Eggy Swarm
• Enter Multiplayer
• Create or join the same multiplayer session
• Ready both players
• Launch the multiplayer session
• Confirm both players enter the same multiplayer game
• Confirm player movement and realtime game state are visible to both users

This final test is important.

The ACP connection test confirms XenForo can reach:

http://127.0.0.1:31338/health

Actual multiplayer additionally confirms that the public:

/swarm-realtime

WebSocket proxy is working correctly for players.

15. Useful PM2 commands​

Check the current Swarm realtime process:

pm2 status

Restart Swarm realtime:

pm2 restart eggy-swarm-realtime

Stop Swarm realtime:

pm2 stop eggy-swarm-realtime

Start it again:

pm2 start eggy-swarm-realtime

View recent logs without leaving a continuous log process running:

pm2 logs eggy-swarm-realtime --lines 50 --nostream

Save the current PM2 processes:

pm2 save

16. Regenerating the realtime secret​

If you regenerate the realtime secret from:

Admin control panel → Eggy Swarm → Multiplayer

restart the Node.js service afterwards:

pm2 restart eggy-swarm-realtime

The realtime service will then load the new secret.

17. Changing the Node.js port​

The port configured in Eggy Swarm and the port used by Node.js must match.

For example, if you change the ACP port to:

31339

the Node.js service must also use port 31339.

You can recreate the PM2 process using:

pm2 delete eggy-swarm-realtime
EGGY_SWARM_HOST=127.0.0.1 EGGY_SWARM_PORT=31339 pm2 start server.js --name eggy-swarm-realtime
pm2 save

Your reverse proxy must then also point to:

127.0.0.1:31339

The following three values must always agree:

• Eggy Swarm ACP Node.js port
• PM2 / Node.js service port
• WebSocket reverse proxy destination port

Troubleshooting​

ACP shows Disconnected​

First check PM2:

pm2 status

Then test Node.js directly:

curl -sS http://127.0.0.1:31338/health

If this fails, the problem is between XenForo and the local Node.js service.

Check the recent PM2 log:

pm2 logs eggy-swarm-realtime --lines 50 --nostream

PM2 shows errored or stopped​

Check the recent log:

pm2 logs eggy-swarm-realtime --lines 50 --nostream

Check the following:

• Node.js is installed and working
• npm dependencies were successfully installed
• You started PM2 from the correct Swarm Realtime directory
• Port 31338 is available
• The Swarm realtime secret exists
• The realtime service has permission to read the required files

ACP shows Connected but multiplayer does not work​

This is an important distinction.

If the ACP shows Connected, then XenForo can successfully communicate with:

http://127.0.0.1:31338/health

However, players connect through:

/swarm-realtime

If the ACP connection test passes but actual multiplayer fails, the most likely area to check is the public WebSocket reverse proxy.

Check the following:

• The /swarm-realtime proxy exists
• The proxy points to the correct Node.js port
• WebSocket Upgrade headers are being forwarded
• Cloudflare is not blocking the WebSocket request
• Your firewall or security software is not interfering with WebSocket traffic
• Your domain has a valid HTTPS configuration

The health check works but players cannot join each other​

A successful health check confirms that the Node.js process is running.

It does not automatically prove that browsers can reach the public WebSocket service.

Check the public path:

/swarm-realtime

and review your nginx, Apache, LiteSpeed or other reverse proxy configuration.

Port 31338 is already in use​

Check what is listening on port 31338:

ss -ltnp | grep ':31338'

If another process is already using the port, either stop the conflicting process or configure Eggy Swarm to use another available port.

Remember that all of the following must use the same port:

• Eggy Swarm ACP Node.js port
• PM2 / Node.js service
• WebSocket reverse proxy destination

Checking PM2 logs​

Use:

pm2 logs eggy-swarm-realtime --lines 50 --nostream

Look for errors relating to:

• Port binding
• Missing Node.js dependencies
• Missing realtime secret
• File permissions
• Invalid environment variables
• Node.js startup errors

Restarting after an Eggy Swarm update​

If the realtime Node.js files have changed after an Eggy Swarm update, reinstall the production dependencies and restart the realtime service.

Go to your Swarm realtime directory:

cd /var/www/vhosts/example.com/httpdocs/src/addons/Eggy/Swarm/Realtime

Then run:

npm ci --omit=dev
pm2 restart eggy-swarm-realtime
pm2 save

Multiplayer stopped after regenerating the secret​

Restart the Swarm realtime service:

pm2 restart eggy-swarm-realtime

Then return to:

Admin control panel → Eggy Swarm → Multiplayer

and click:

Test realtime connection

Recommended configuration​

For most installations there should be no reason to change the standard Eggy Swarm settings:

Enable multiplayer: Yes
Node.js host: 127.0.0.1
Node.js port: 31338
Public WebSocket path: /swarm-realtime

Keeping Node.js bound to 127.0.0.1 means the realtime service remains private and players access it through your normal secured website connection.

Setup complete​

Your Eggy Swarm realtime multiplayer setup is complete when:

• PM2 shows eggy-swarm-realtime as online
• http://127.0.0.1:31338/health responds successfully
• Eggy Swarm ACP shows Connected
• The /swarm-realtime WebSocket proxy is configured
• Two separate XenForo users can successfully enter the same multiplayer session
• Both players can see realtime movement and game state

If the ACP test shows Connected but actual multiplayer does not work, concentrate on the public WebSocket/reverse proxy configuration rather than repeatedly reinstalling Node.js.