🌐 Part of the BiosSystem Suite

OriginalMS is a modern, Dockerized classic MapleStory v62 (GMS 2008) server emulator. It ships with all Party Quests working, Cygnus Knights, Aran, bosses, and a fully localized English UI. Zero local environment setup required.

graph TB
    subgraph Docker["Docker Compose Stack"]
        subgraph Server["OriginalMS Server (Java 8)"]
            MINA["Apache MINA Network Engine"]
            CHAN["Channel Server(s)"]
            LOGIN["Login Server"]
            SHOP["Shop Server"]
            NPC["NPC / Quest / Portal Scripts (JS)"]
        end
        subgraph DB["Database"]
            MYSQL["MySQL / MariaDB"]
        end
    end

    subgraph Client["Game Client (External)"]
        EXE["MapleStory.exe / localhost.exe"]
        WZ["WZ Data Files (External)"]
    end

    EXE -->|"TCP Port 8484"| LOGIN
    LOGIN --> CHAN
    CHAN --> MINA
    MINA --> NPC
    MINA --> DB
    MYSQL --> CHAN
    WZ --> EXE

This project uses a strict 3-branch architecture:

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'mainBranchName': 'OdinMS'}} }%%
gitGraph
   commit id: "OdinMS base source"
   commit id: "v1.0.0-base: raw upstream"

   branch classic
   checkout classic
   commit id: "v1.1.0-classic: PQ fixes"
   commit id: "English localization"
   commit id: "v3.0.0-v62: Cygnus Aran & Bosses"

   branch main
   checkout main
   commit id: "v2.0.0-docker: Dockerized stack"
   commit id: "v3.0.0-v62: Parity Release"

• All Party Quests (Kerning PQ, Ludibrium PQ, Orbis PQ, Monster Carnival PQ, Amoria PQ, Pirate PQ) work end-to-end
• Cygnus Knights (Noblesse, Dawn Warrior, Blaze Wizard, Wind Archer, Night Walker, Thunder Breaker) and Aran class job enum registration and 5-byte packet decoding
• Complete boss suites for Zakum, Horntail, and Papulatus with server-side phase enforcement
• Authentic GMS v62 Gachapon tables rebuilt across all 12 game locations
• Complete Nautilus Harbor NPC coverage and English localization scrub across NPC scripts
• Exploits and dupe bugs from base OdinMS patched

To comply with licensing rules, three items must be sourced separately:

Step 1. Clone the main branch (Docker deployment):

git clone --branch main https://github.com/BiosSystem/OriginalMS.git
cd OriginalMS

Step 2. Place your WZ data files:

# Copy your extracted WZ folder into the project root
cp -r /path/to/your/wz ./wz

Step 3. Build the Java server:

mvn clean package -DskipTests

Step 4. Start the full stack with Docker Compose:

docker compose up -d

This starts the MySQL database and the OriginalMS server together. The server is ready when you see Listening on port 8484 in the logs.

Step 5. Connect your game client:

Point your v62 localhost.exe at 127.0.0.1:8484 and log in with the default admin account (admin / admin).

Step 6. Check server logs:

docker compose logs -f originalms

If you prefer to run without Docker, use the classic branch and set up MySQL manually:

git clone --branch classic https://github.com/BiosSystem/OriginalMS.git
cd OriginalMS

# Import the database schema
mysql -u root -p < sql/install.sql

# Edit config
nano launch/config.properties  # set DB host, user, password

# Build and run
mvn clean package -DskipTests
java -jar target/OriginalMS.jar

• 🚀 Quick Start Guide - Step-by-step installation and client connection
• 🎮 GM Commands Reference - Full reference for player and GM commands
• 🐉 Boss Guides - Zakum, Horntail, and Papulatus mechanics and entry requirements
• 🧩 Party Quest Guide - Level ranges, entry NPCs, and rewards for all active PQs
• 🛠️ Troubleshooting Guide - Common setup issues, network fixes, and DB notes
• 🏠 Wiki Index - Complete documentation sitemap