🌐 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:

gitGraph
   commit id: "OdinMS base source"
   branch OdinMS
   checkout OdinMS
   commit id: "v1.0.0-base: raw upstream"

   checkout main
   branch classic
   commit id: "v1.1.0-classic: PQ fixes + game patches"
   commit id: "English localization"
   commit id: "Exploit fixes"

   checkout main
   merge classic
   commit id: "v2.0.0-docker: Dockerized deployment"
   commit id: "Docker Compose + health checks"

• All Party Quests (Kerning PQ, Ludibrium PQ, Orbis PQ, etc.) work end-to-end
• Cygnus Knights and Aran class progression fully functional
• Boss spawn timers and HP/drops corrected
• NPC dialogue fully translated to English
• Exploits and dupe bugs from the 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

Full setup guides and GM commands are in the Wiki.