Cluster Mode

Overview

Cluster mode lets several worldservers serve a single realm, splitting players and maps between them. Each worldserver can declare which maps it is willing to handle; ToCloud9 then assigns maps across the fleet and redirects players to the right worldserver when they change map.

AzerothCore only provides the integration points (config, map assignment hooks, login/redirect path, and the sidecar C API). The distributed logic lives in ToCloud9: service discovery, the gateway clients connect to, shared GUID pools, and the auth, characters, guild, mail, auction house, chat, group and matchmaking services.

For the architecture and the reasoning behind it, see the ToCloud9 README and the AzerothCore discussion.

Building

AzerothCore talks to ToCloud9 through libsidecar, a shared library from the ToCloud9 repository.

By default the core builds against an in-tree stub of that library, so cluster code compiles but does nothing. Normal (non-cluster) builds need no extra dependencies and are unaffected.

To run cluster mode you must link against the real library. The supported implementation is libsidecar-cpp (native C++, same C ABI).

1. Build libsidecar-cpp

In a ToCloud9 checkout:

cd game-server/libsidecar-cpp
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF
cmake --build . --config Release

On Windows, use an x64 Native Tools / VS generator, for example:

cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF
cmake --build . --config Release

Pre-built Windows binaries are also published on the ToCloud9 releases page (libsidecar-cpp-windows-x64-v143 for VS 2022, v142 for VS 2019).

2. Install the library into AzerothCore

Place the artifacts under deps/libsidecar/ of your AzerothCore source tree. CMake expects the shared library next to that directory’s CMakeLists.txt (not only under a nested lib/), and the C headers under include/.

On macOS and Linux, libsidecar-cpp is built with VERSION / SOVERSION, so the build directory contains three related names — one real binary and two symlinks. Copy all of them and preserve the symlinks (do not flatten them into three full copies).

AzerothCore’s CMake looks up the unversioned name (libsidecar.dylib / libsidecar.so / libsidecar.dll). The loader still follows the symlink chain to the real binary, so omitting the versioned file or breaking the links will fail at link or run time.

Also keep the headers in sync with the library you built:

deps/libsidecar/include/   ← copy from ToCloud9 game-server/libsidecar-cpp/include/

The cluster-mode tree already ships matching headers; replace them when you upgrade libsidecar.

Example (macOS / Linux, after a Release build of libsidecar-cpp). Use cp -a so the two symlinks stay symlinks:

# macOS
cp -a game-server/libsidecar-cpp/build/libsidecar*.dylib /path/to/azerothcore/deps/libsidecar/
# Linux
# cp -a game-server/libsidecar-cpp/build/libsidecar.so* /path/to/azerothcore/deps/libsidecar/

cp game-server/libsidecar-cpp/include/*.h /path/to/azerothcore/deps/libsidecar/include/

# runtime loader also needs the same trio (real file + two symlinks):
sudo cp -a game-server/libsidecar-cpp/build/libsidecar*.dylib /usr/lib/   # macOS
# sudo cp -a game-server/libsidecar-cpp/build/libsidecar.so* /usr/lib/  # Linux

On Windows, copy libsidecar.dll next to worldserver.exe (or onto PATH) in addition to deps/libsidecar/ for linking.

3. Configure AzerothCore with the real library

Pass the CMake option -DUSE_REAL_LIBSIDECAR=ON when configuring the core.

The CMake summary confirms the choice with:

* Use stub for libsidecar         : No

If that line still says Yes, the real library was not selected or was not found where CMake expects it.

Configuration

The options live in the CLUSTER SETTINGS block at the end of worldserver.conf. See How to work with Conf Files before editing.

Like other AzerothCore settings, these can be overridden with environment variables (AC_CLUSTER_ENABLED, AC_CLUSTER_AVAILABLE_MAPS, AC_CLUSTER_IS_CROSSREALM, and related ports such as AC_WORLD_SERVER_PORT). Sidecar service endpoints are configured separately via TC9_* / service env vars documented in ToCloud9.

You must also run the ToCloud9 microservices (at least servers-registry, guidserver, gateway, authserver, and the services you rely on for guild/mail/chat/group/auction/matchmaking) and point libsidecar at them. Do not run AzerothCore’s own authserver for that realm when using the ToCloud9 auth path.

Running a cluster

Setup instructions are maintained in the ToCloud9 repository:

• Docker Compose — quickest way to get a full cluster
• Helm chart — Kubernetes
• Windows + WSL, without Docker
• Windows native, without Docker (libsidecar-cpp)
• Linux / macOS without Docker: build libsidecar-cpp as above, configure the core with -DUSE_REAL_LIBSIDECAR=ON, apply ToCloud9 SQL migrations for the characters DB, start the ToCloud9 services, then run one or more worldservers with Cluster.Enabled = 1 (and distinct ports / TC9_GRPC_PORT / TC9_HEALTH_CHECK_PORT per process)

Minimal multi-worldserver example (after services are up):

# worldserver A
AC_CLUSTER_ENABLED=1 AC_WORLD_SERVER_PORT=9601 ./worldserver

# worldserver B (override sidecar ports so they do not clash)
AC_CLUSTER_ENABLED=1 AC_WORLD_SERVER_PORT=9602 \
  TC9_GRPC_PORT=9603 TC9_HEALTH_CHECK_PORT=9604 ./worldserver

# optional: pin a process to a single map (e.g. Icecrown Citadel)
AC_CLUSTER_ENABLED=1 AC_CLUSTER_AVAILABLE_MAPS=631 AC_WORLD_SERVER_PORT=9605 \
  TC9_GRPC_PORT=9606 TC9_HEALTH_CHECK_PORT=9607 ./worldserver

Getting help

Cluster mode issues that are not specific to the AzerothCore side belong in the ToCloud9 issue tracker or its Discord channel.