BeiDou Server: a MapleStory server, its API versioning, and its web front end

A fork of Cosmic, localized and extended

BeiDou-Server is described as a global MapleStory server, and the README is explicit about its lineage: the project is based on the Chinese localization and optimization of Cosmic, whose repository is given.

The name is explained at some length. BeiDou is the Chinese name for the BeiDou Navigation Satellite System, also known as COMPASS, described as a global satellite navigation system developed by China and the third mature system after GPS and GLONASS. The narrative goes on to say that the project aims to be better and stronger than both HeavenMS and Cosmic.

That framing tells you what kind of project this is. It is a community reimplementation of a game server, the kind of project that exists because a game's server protocol is not publicly documented and someone reverse engineered it. The primary language is Java for the server side and JavaScript for the web front end, the licence is AGPL-3.0, the default branch is master, and the last push was on 2026-10-11.

The releases are frequent and small in scope. Version 1.10.1 is dated 2026-02-26, 1.11 on 2026-05-31, and 1.12 on 2026-08-08. There is a wiki page tracking development progress, and the wiki has been opened up so that anyone can edit it, which is a reasonable way to handle a project where the same questions get asked repeatedly.

The top level of the tree is small and split by concern: a gms-server directory for the Java backend, a gms-ui directory for the web front end, a pom.xml for the Maven build, an AGENTS.md and a CLAUDE.md for the tooling expectations of contributors, and the usual repository files.

The API on port 8686 and how endpoint versioning works

The server side exposes an HTTP API on port 8686, and Swagger is wired in, with the UI at localhost:8686/swagger-ui/index.html. That is the single most useful thing to know if you want to understand what the server does, because it makes the endpoint surface browsable rather than something you have to read the source to discover.

The versioning scheme is described precisely. Endpoints are controlled by version, with v1, v2 and v3 as the examples, and the default Swagger tag is ApiConstant.LATEST with the default RequestMapping set to the API constant followed by a slash and the path.

The rule for changing versions is the part that shows the design was thought through. If a new version is added and the interfaces do not need to change, you only point ApiConstant.LATEST at the new version. If some interfaces are not backward compatible, you change the Tag and the RequestMapping of the old interfaces to a specific version such as ApiConstant.V1, and everything else follows LATEST. So compatible endpoints move as a group, and only the breaking ones are pinned.

That is a small but real design decision, and it is the kind of thing that decides whether an API can be versioned in practice or whether the versioning turns into a mess after two releases.

The server also handles the database for you. Automatic database creation is implemented, and the initialisation SQL script is run, so the only requirement is that MySQL is running. The README is direct that MySQL versions below 8 are not supported.

Multi-language assets, and why the paths matter

The server supports multiple languages, and the implementation detail is that the scripts and the wz data are read from different paths depending on the locale. The path names given are wz-zh-CN and wz-en-US for the data and script-zh-CN and script-en-US for the scripts.

That is worth a sentence of its own, because it is a common structural decision in this kind of project. The wz files are the game's data assets, and having them in per-locale directories means a locale is a directory swap rather than a set of conditionals scattered through the asset loading code. The same applies to the scripts.

For a developer reading the codebase, the consequence is that searching for an asset name will turn up two copies, and the directory prefix is how you know which one you are looking at. It also means a new locale is a new set of directories, which is the cheap way to add one.

The rest of the environment for the server side is a straightforward modern Java stack: OpenJDK 21, Intellij IDEA 2023.3 or newer, MySQL 8 with a link to a MySQL build tool and to the community downloads, Maven and git. A database client is also listed, with DBeaver and Navicat Lite as the two named options. The MySQL 8 requirement and JDK 21 are both modern enough that this is not a project pinned to an old toolchain.

The web front end and its Node setup

The gms-ui directory holds the web front end, and its setup is documented step by step with the expectation that readers will skip the steps they have already done.

The first step is installing NodeJS v20.15.0, the LTS version, with a direct download link given. The second is installing Yarn, which is done through npm:

npm install -g yarn

The third step initialises the front end development environment, which means entering the gms-ui directory and running:

yarn install

And the fourth starts the development environment:

yarn dev

The Yarn choice is worth a note. Yarn rather than npm means lockfile behaviour and install output differ from a default npm project, and the documented install command is a global yarn install, which is one more step than most teams would expect but is the conventional setup for this kind of project.

There is one honest caveat in the remarks section. All the images in the web front end have to be fetched over the network, and the credit goes to maplestory.io for the image interface. So the front end is not self-contained: a clone of the repository does not give you a working interface offline, and the asset availability depends on a third party service that the project does not control.

Releases, the client, and Docker in a separate repository

The client and server are already packaged in the GitHub releases, and the README says to download them directly from there. For people who want an earlier beta of the BeiDou client there is a separate wiki page about its early releases. So this is a project that expects people to run it rather than to build it, which changes what a reader should look for.

The Docker configuration is the other structural thing. The docker configuration that was in the original server has been removed, and the configuration now lives in a separate repository, BeiDou-docker. That repository also publishes a prebuilt container image, and contributors who want to work on Docker are pointed there for pull requests.

Splitting Docker out is a defensible choice, since it separates the image build from the application source, but it means a single clone is not enough to run the whole thing in containers. You need both repositories, and the image in the packages section of the new one is the fastest route if you are not developing.

The wiki is the third support channel, and the README says most questions are already answered there, that issues are welcome for anything missing, and that the wiki has been made editable by everyone. The last point is unusual and worth respecting as a design decision: for a project of this size, keeping the documentation in the repository and letting anyone improve it is a better use of effort than a support queue.

On the licensing side, the project is AGPL-3.0, which is the copyleft licence with the network clause, and it is a heavier obligation than MIT or Apache for anyone who modifies and offers the result over a network.

Editorial conclusion

Adopt this codebase if you are studying how a legacy game protocol is reimplemented in Java, since the API versioning scheme, the multi-language asset paths and the split between server, web and Docker repositories are all documented, and the Swagger UI makes the surface explorable at localhost:8686. Keep away if you need a supported, licence-clean production game backend, because the project is an AGPL-3.0 community reimplementation whose client is distributed in releases and whose images live in a separate repository. Before you build on it, check the MySQL 8 requirement, because versions below that are not supported, and note that the Docker configuration has been removed from this repository into BeiDou-docker, so you have to follow it there.

Frequently asked questions

Official sources

1. BeiDouMS/BeiDou-Server on GitHub
2. Issues
3. License: AGPL-3.0
4. README
5. Releases