Onder de motorkap van BeiDou-Server: Een moderne kijk op MapleStory server-emulatie met Java 21

Wie de gouden eeuw van client-side MMORPG's in het late 2000-tijdperk heeft meegemaakt, herinnert zich waarschijnlijk MapleStory. Op zijn hoogtepunt voedde deze 2D-grindgame een enorme fancommunity. Privéservers in die tijd waren in elkaar geflanst: pak de OdinMS- of HeavenMS-broncode, plak er een hoop patches voor Java 6 op, importeer handmatig een enorme databasedump via een oude versie van Navicat, en hoop dat het niet crasht zodra honderd spelers verbinden.

De meeste van deze emulators bleven steken in vijftien jaar oude legacy code. De ontwikkelaars van het BeiDou-Server project kozen voor een andere aanpak. Voortbouwend op het Cosmic project stelden ze zich ten doel om de server-side code te herschrijven en te optimaliseren met een modern tech stack: JDK 21, MySQL 8, REST API met Swagger en een geïsoleerde Node.js frontend voor administratie.

Waar de BeiDou-Server architectuur uit bestaat

Het project is opgesplitst in twee hoofdcomponenten: de backend gms-server, verantwoordelijk voor game-logica en API, en de webinterface gms-ui. De ontwikkelaars hebben de ondersteuning voor oudere MySQL-versies laten vallen — versie 8.0 of hoger is vereist om te draaien.

De meest aangename verrassing bij de eerste blik op de code is de automatisering van routinematige taken bij de eerste start. De server controleert automatisch op het vereiste schema in de DBMS, maakt tabellen aan en past initiële SQL-scripts toe. Er is niet langer behoefte aan het installeren van third-party utilities voor database-import.

Backend architectuur hoogtepunten

• Migratie naar OpenJDK 21. Door de nieuwste Java-versie te gebruiken was het mogelijk om verouderde constructies te elimineren en moderne taalfuncties toe te passen bij het afhandelen van netwerkpakketten en geheugenbeheer.
• REST API op poort 8.686. De ontwikkelaars hebben Swagger UI geïntegreerd, dat direct beschikbaar is nadat de service start. Dit vereenvoudigt het debuggen en de integratie met externe services enorm.
• Endpoint versioning. Het project implementeert een schone API versioning schema via de ApiConstant.LATEST constante. Als een methode niet is veranderd in de nieuwe applicatieversie, is er geen noodzaak om het te dupliceren — routing leidt verzoeken automatisch door naar de huidige controller.
• Meertalige resource engine. De server kan gelokaliseerde game-data en scripts dynamisch laden uit verschillende directories (bijvoorbeeld wz-zh-CN voor Chinees of script-en-US voor Engels).

Web admin panel en graphics verwerking

De interface gms-ui is gebouwd op Node.js v20.15.0 met de Yarn package manager. In tegenstelling tot oude emulators waar het admin panel een rommeltje van Swing-formulieren binnen de server zelf was, is hier het panel volledig webgebaseerd.

Het probleem van het opslaan en weergeven van duizenden item sprites, monsters en map graphics wordt elegant opgelost. Om te voorkomen dat de repository opgeblazen wordt met gigabytes aan grafische assets, vraagt het web panel afbeeldingen rechtstreeks aan via de externe API van de maplestory.io service.

Container deployment en beheer

Deployment en werken met containers

Voorheen leefden Docker configs direct in de hoofdrepository, maar in de loop der tijd verplaatsten de auteurs alles met betrekking tot containerisatie naar een apart project BeiDou-docker. Een kant-en-klare image beidou-server-all is al beschikbaar in GitHub Packages, dus je kunt een testomgeving in slechts een paar minuten deployen zonder van broncode te bouwen.

Voor lokale ontwikkeling heb je de standaard tools nodig:

• OpenJDK 21
• IntelliJ IDEA 2023.3 of nieuwer
• MySQL 8 DBMS
• Git en Maven

Voorgebouwde server binaries en clients zijn beschikbaar in de Releases sectie, en voor degenen die experimentele builds willen testen is er een aparte branch met vroege bèta-versies.

Mogelijke uitdagingen waar je tegenaan kunt lopen

De belangrijkste kanttekening bij BeiDou-Server is de taalbarrière. Het project is gemaakt door een Chinese gemeenschap, dus de meeste code comments, issue discussies en Wiki-pagina's zijn in het Chinees geschreven.

Echter, met Swagger en een duidelijke directory structuur is navigeren door de code veel gemakkelijker geworden, zelfs zonder kennis van de taal. Bovendien hebben de auteurs de project Wiki volledig open gesteld voor community-bewerking, dus documentatie wordt geleidelijk ook in het Engels aangevuld.

Voor wie kan dit project interessant zijn

BeiDou-Server is een geweldig voorbeeld van hoe enthousiastelingen monsterlijke legacy code van een oud online spel omtoveren tot een begrijpelijk project met een moderne stack.

Als je geïnteresseerd bent in game-ontwikkeling, wilt verkennen hoe MMORPG netwerkprotocollen werken, echte voorbeelden wilt zien van multi-versie REST API-organisatie in Java, of gewoon nostalgisch bent naar oude spellen — deze broncode is zeker de moeite waard om te bekijken.